angular-cli/docs/process/release.md

Setting Up Local Repository

1. Clone the Angular-CLI repo. A local copy works just fine.
2. Create an upstream remote:

$ git remote add upstream https://github.com/angular/angular-cli.git

Caretaker

The caretaker should triage issues, merge PR, and sheppard the release.

Caretaker calendar can be found here.

Each shift consists of two caretakers. The primary caretaker is responsible for merging PRs to master and patch whereas the secondary caretaker is responsible for the release. Primary-secondary pairs are as follows:

Primary	Secondary
Alan	Doug
Charles	Keen
Filipe	Minko

Triaging Issues

TBD

Merging PRs

The list of PRs which are currently ready to merge (approved with passing status checks) can be found with this search. This list should be checked daily and any ready PRs should be merged. For each PR, check the PR target label to understand where it should be merged to. If master is targetted, then click "Rebase and Merge". If the PR also targets a patch branch, see Maintaining Patch Branches. Whatever the target, rebasing should be used over merging to avoid cluttering the Git history with merge commits.

Maintaining Patch Branches

When a PR is merged, if the PR target label includes a branch other than master, commits will need to be cherry-picked to an associated branch. In particular, the patch target simply refers to the latest patch branch (eg. 1.2.x or 1.3.x-rc.0). This branch should be updated by cherry-picking all applicable commits to it, such as those with messages beginning with fix(), docs(), or refactor().

Say the following PR is merged;

* fix(@angular/cli): fix path when doing stuff
* refactor(@angular-devkit/core): replace Fizz with Buzz
* feat(@angular-devkit/core): add new feature
* fix(@angular-devkit/core): fix something related to new feature
* refactor(@angular-devkit/core): move stuff to new feature

Only the first 2 commits should be cherry picked to the patch branch, as the last 3 are related to a new feature.

Cherry picking is done by checking out the patch branch and cherry picking the new commit onto it. The patch branch is simply named as a version number, with a X in the relevant spot, such as 9.0.x. This should be done after merging to master.

# Make sure commit to upstream/master is present in local repo.
git fetch upstream master

# Check out patch branch from upstream.
git fetch upstream <patch branch>
git checkout <patch branch>

# Cherry pick the commit. Use the hash from the commit which was merged
# into upstream/master, which should be known to your local repo.
git cherry-pick -x <commit hash from master>
# If you have multiple cherry picks, you can do them all here.

# Resolve merge conflicts if necessary...
# Or abort and ask author to submit a separate commit targeting patch-only.

# Push changes.
git push upstream <patch branch>

If you get a bad revision error when cherry picking, make sure you are using the commit hash used when merged into master, not the hash listed in the PR. Also verify that you have fetched master from upstream since that commit was merged.

If the commit is not merged to master (because it targets patch only for instance), then you will need to fetch the contributor's branch for your local Git instance to have knowledge of the commit being cherry picked onto the patch branch.

Maintaining LTS branches

Releases that are under Long Term Support (LTS) are listed on angular.io.

Since there could be more than one LTS branch at any one time, PR authors who want to merge commits into LTS branches must open a pull request against the specific base branch they'd like to target.

In general, cherry picks for LTS should only be done if it meets one of the criteria below:

1. It addresses a critical security vulnerability.
2. It fixes a breaking change in the external environment. For example, this could happen if one of the dependencies is deleted from NPM.
3. It fixes a legitimate failure on CI for a particular LTS branch.

Release

Before releasing

Make sure the CI is green.

Consider if you need to update packages/schematics/angular/utility/latest-versions.ts to reflect changes in dependent versions.

Shepparding

As commits are cherry-picked when PRs are merged, creating the release should be a matter of creating a tag.

Make sure you update the package versions in packages/schematics/angular/utility/latest-versions.ts.

git commit -a -m 'release: vXX'
git tag 'vXX'

The package versions we are about to publish are derived from the git tag that we just created. Double check that the versions are correct by running the following command.

yarn admin packages --version

Now push the commit and the tag to the upstream repository. Make sure to run these commands together, as missing tags can cause CI failures.

git push upstream && git push upstream --tags

Authenticating

This can ONLY be done by a Google employee.

Log in to the Wombat publishing service using your own github and google.com account to publish. This enforces the loging is done using 2Factor auth.

Run npm login --registry https://wombat-dressing-room.appspot.com:

1. In the new browser tab, the registry app will ask you to connect with GitHub to create a token
2. After connecting with github, you will be redirected to create a token
3. Upon redirect, an auth token is added to your ~/.npmrc for the proxy

After closing the tab, you have successfully logged in, it is time to publish.

NOTE: After publishing, remove the token added to your ~/.npmrc file to logout.

Publishing

This can ONLY be done by a Google employee.

It is a good idea to wait for CI to be green on the patch branch and tag before doing the release.

For the first release of a major version, follow the instructions in Publishing a Major Version section.

For non-major release, check out the patch branch (e.g. 9.1.x), then run:

yarn # Reload dependencies
yarn admin publish

If also publishing a prerelease, check out master, then run:

yarn # Reload dependencies
yarn admin publish --tag next

Release Notes

yarn run -s admin changelog takes from and to arguments which are any valid git ref.

For example, running the following command will output the release notes on stdout between v1.2.3 and 1.2.4:

yarn run -s admin changelog --from=v1.2.3 --to=v1.2.4

Copy the output (you can use | pbcopy on MacOS or | xclip on Linux) and paste the release notes on GitHub for the tag just released.

If you have an API token for GitHub you can create a draft automatically by using the --githubToken flag. You just then have to confirm the draft.

Tags containing beta or rc should be marked as pre-release.

Microsite Publishing

The microsite is the landing page for Angular CLI and is a one-page static page.

This can ONLY be done by a Google employee.

You will need firebase access to our cli-angular-io firebase site. If you don't have it, escalate.

Check out if changes were made to the microsite:

git log v8.0.0-beta.0..HEAD --oneline etc/cli.angular.io | wc -l

If the number is 0 you can ignore the rest of this section.

To publish, go to the angular-cli/etc/cli.angular.io directory and run firebase deploy. You might have to firebase login first. If you don't have the firebase CLI installed, you can install it using npm install --global firebase-tools (or use your package manager of choice).

This is detailed in etc/cli.angular.io/README.md.

Publishing a Major Version

For the first release of a major version, say v10.0.0, checkout the major branch (i.e. 10.0.x), then run:

yarn # Reload dependencies
yarn admin publish --tag next # a major release is always tagged as next initially

Confirm with downstream repositories (Components, etc) that everything is ok. Once the release is stable, wait for Framework to retag their packages, then retag the CLI packages as latest. The command below will automatically retag stable packages as well as experimental packages.

yarn admin dist-tag --version 10.0.0 --tag latest