When publishing an NPM package, it is common practice to include a CHANGELOG.md file to inform your consumers about bug fixes, new features, and changed or removed functionality. Rush automates this using the rush change command. This command should be run once you are ready to merge your PR, after all your changes have been committed to the branch. It analyzes the changes in your branch and (when necessary) prompts you to write human-readable descriptions of your changes. Authoring change logs
This generator adds support for change file generation based on conventional commits convention.
The difference between commit messages and rush's change files is explained by Pete Gonzalez:
Git commits document steps of work. For example, when I create a PR, I might break it into 5 separate commits that are easier to review one by one, rather than reading the entire PR diff. And then during the code review, people may suggest various improvements, which may lead to 10 more commits before I finally merge my PR. Some of these commits will be pure bookkeeping (
ran "rush update"
,merged from master
, etc). Git commits are written for the audience of people who work on the code. Whereas...Change logs inform consumers what's new. Consumers need to know which bugs got fixed, which new features were added, or alert consumers about possible breaking changes. This audience often doesn't know anything about the underlying implementation, so a different style of writing is needed. In a monorepo, one Git commit might impact many different projects, and perhaps in a way that needs to be explained differently for each project. For certain important projects, the change log may serve as a public announcement to customers. The release team may have a step where they manually revise the changelog before publishing a release.
If you follow Conventional Commits, your commits already contain information necessary for calculating the change type.
rush change
detects changed projects based on your staged files and commits.
rush whatchanged
always displays number of commits and staged files for each project. It only analyzes commits made after the last commited change file.
- when used with
--recommend-changetype
it suggests a change type for each changed project, based on your commits since the 'mergeBase' detected by rush. - when used with
--show-commits
it displays (--show-commits shortlog
) or saves to a file (--show-commits full
) history of your commits made since the 'mergeBase'.
Important: This solution is using ProjectChangeAnalyzer class which is still in BETA and may change. It is NOT recommended to use this API in a production environment.
When detecting existing change files,
rush
only retrieves a list of already commited change files. Therush whatchanged
command is aligned withrush
and also only retrieves a list of already committed change files. This influences the detected "last created date" of the change file, and the timestamp from which the commits are analyzed.rush
does NOT automatically commit change files.
usage: rush whatchanged [-h] [-b BRANCH] [--recommend-changetype] [--show-commits {shortlog,full}]
Provides support for creating change files.
Optional arguments:
-h, --help Show this help message and exit.
-b BRANCH, --target-branch BRANCH
If this parameter is specified, compare the checked
out branch with the specified branch to determine
which projects were changed. If this parameter is not
specified, the checked out branch is compared against
the "main" branch.
--recommend-changetype
Parses commit messages included in the same revision
range as the one used by rush change. Based on the
commit type, suggest change type: 'major', 'minor',
'patch' or 'none'
--show-commits Display commits included in the revision range used
by rush change.
usage: rush commitlint [-h] [--edit]
Used by the commit-msg Git hook.
This command invokes commitlint to ensure that the commit messages meet the conventional commit format.
The rules are defined in `commitlint.config.js` file; see https://commitlint.js.org/#/reference-rules for possible options.
-h, --help Show this help message and exit.
--edit The commit message provided by a user
This generator requires that your project is managed with rush. Run the following commands to initialize it:
rush init
rush update
First, install Yeoman and generator-rush-conventionalcommits using npm.
npm install -g yo
npm install -g generator-rush-conventionalcommits
If not already done, configure git and rush:
git init
rush init
rush update
and follow Adding projects to a repo to configure which projects are managed by rush.
Then add the conventional commits support:
yo rush-conventionalcommits
This generator creates the following resources:
-
rush-commitlint: rush autoinstaller installing:
@commitlint/cli
and@commitlint/config-conventional
-
rush-changemanager: rush autoinstaller installing:
@microsoft/rush-lib
,@rushstack/node-core-library
,yargs
andconventional-commit-types
rush commitlint
runscommitlint
on the commit messages; used by the commit-msg Git hook.rush whatchanged
'explains' why change file is required, by printing number of commits and staged files for each project. It also provides recommendation for a change type, and prints commits history (console or a file in a rush temp folder)
- commit-msg invokes
rush commitlint
to ensure the commit message has correct format - pre-push (optional) invokes
rush change -v
to verify change files are generated for changed projects
Important: Rush will install git hooks during
rush update
executed as part of this generator. For this step to succeed, you must initialize the git repo first. Otherwise, please execute therush update
command manually, once you are ready.
- Display commits history: For each project returned by
projectAnalyzer.getChangedProjectsAsync
, display commits history since merge base, by executing
git shortlog ${mergeHash}... ${since} -- "${project.projectRelativeFolder}"
or
git --no-pager log ${mergeBaseHash}... ${since} -- "${projectRelativeFolder}" > ${targetPath}
- Suggest change type For each project returned by
projectAnalyzer.getChangedProjectsAsync
, obtain commits indicating major/minor/patch change, using
git rev-list --count --extended-regexp --grep ${regex} -- ${projectFolder}
The conventional commit types are retrieved from conventional-commit-types.
To limit parsed commits, the merge base is retrieved using
git --no-optional-locks merge-base -- HEAD ${branchName}
This is the same command as used by ProjectChangeAnalyzer
in this._git.getMergeBase
invocation.
- make a change in any of the projects managed by rush (listed in rush.json)
git add .
git commit -m "fix: testing rush change file generation"
rush whatchanged --recommend-changetype
- observe the information printed to the terminal. The first time a rush command depending on an autoinstaller is executed, rush will install Rush engine, package manager, dependencies defined in the autoinstaller. The next time, the command will execute much faster.
- see the recommendation for the change type
This generator requires rush 5.66.2. If you are using older version, and are not yet ready to upgrade, you may "downgrade" this solution.
Update the common\autoinstallers\rush-changemanager\package.json file. Change:
"@microsoft/rush-lib": "^5.66.2",
"@rushstack/node-core-library": "^3.45.2",
to:
"@microsoft/rush-lib": "^5.64.0",
"@rushstack/node-core-library": "^3.45.0",
Rush 5.64.0 introduces --quiet
command for suppressing startup information.
Apart from updating common\autoinstallers\rush-changemanager\package.json to reference correct version of rush modules, update the git hooks
to remove the --quiet
flag.
See the Rush and Conventional Commits Series for detailed description. npm publish