Angular Dev-Infra release script

There are two phases for cutting a release. Staging and publishing.

Staging:

A release is staged before publishing and the pure intention is to prepare the release output, changelog before publication. The following steps are currently performed in the Angular Components release tooling:

1. Determining the type of release. e.g. "Do you want to release a patch version"
   • This can happen interactively through an option prompt
2. Determine a unique name of the release (for changelog generation). e.g. tin-hat
3. Ensure the proper branch is checked out
   • Can be checked out automatically.
4. Ensure that release is passing for the branch the release is intended to be cut from.
5. Ensure local Git branch is up-to-date with upstream.
6. Create a new branch for release staging.
   • This is done so that the changelog and version bump can go through a pull request with review.
7. Update package.json and store changelog in the release staging branch.
8. Create commit & ask user to create PR for the release target branch.

Publishing:

Publishing happens after the release has been staged and the changelog & version bump
have been merged into the target branch. Once that happened and CI passes for that
staging commit, the actual publish can start. The following steps are performed:

1. Expects active release-train branch to be checked out.
2. Expects latest commit in version-branch to be a version bump/stage commit.
3. Expects upstream to match with locally checked out branch.
4. Building release output
5. Running release output validations
6. Creating version tag and pushing to upstream
7. Publish to NPM upon manual confirmation (for double-checking)
8. Draft release in Github UI w/ release notes so that users are notified.
   • Release notes are automatically extracted from the changelog.
9. Delete .npmrc file to prevent accidental future releases/credential exposure

Release prompt options:

The script should detect the state of the project. e.g. if there is an active release candidate, if there is a feature-freeze ongoing. Based on the state, it will propose options for cutting an release. For example, if there is no active feature-freeze release-train, then no option for cutting an RC is shown. We show the following options to the caretaker:

Always:

• Cut a new patch release. Publishes a new patch version from the patch branch.
• Configure "next" to major mode. Configures next to be a major version by updating the version in master (so that major changes can be landed in the next release-train).

If there is no active feature-freeze/release-candidate:

• Move "next" into feature-freeze. Moves next into the feature-freeze phase.
• Cut a next pre-release (major or minor). Publishes a new "next" version for master.

If there is an active feature-freeze:

• Cut feature-freeze next pre-release. Cuts a new next pre-release for the current active feature-freeze/release-candidate branch.
• Cut release-candidate. Cuts a release candidate for the current FF/RC branch and sets the version to rc.0.

If there is an active release-candidate:

• Cut release-candidate. Cuts a release candidate for the current RC branch and increments the RC pre-release label.
• Cut stable {major|minor}. Cuts a stable major/minor from the active release-candidate branch. This branch will become the latest release-train. The previous patch branch will become inactive (unless it became active for LTS).

Cutting a new patch release

The release tooling will check out the latest release-train branch (i.e. the patch branch) and perform the steps of Staging and Releasing. The new incremented version will always be published under the latest NPM distribution tag.

Changelog needs to be cherry-picked back into the master branch.

Cutting a next pre-release (major or minor)

Depending on the type of the next release-train, a pre-release is cut for a major or minor version. It can detect the type by looking whether the version matches X.0.0-<..>.

The pre-release label will be incremented and the steps of Staging and Releasing are performed. The version is only published within the next NPM distribution tag.

No need to cherry-pick the changelog as the generation and staging already happened directly in the next (i.e. master) branch.

Configure "next" to major mode

This option can be selected by the caretaker if the team decided to start working on the next major version. It will switch the version from a minor mode to major so that major changes can land in the next branch (i.e. master).

Move next into feature-freeze

Moves the current next version into the feature-freeze phase. This means that the release tooling creates a new version-branch based on version in master. A new next pre-release version with the start of the feature-freeze is being cut (going into the next NPM dist tag).

Also the version in master needs to be updated if a major release-train moved into feature-freeze. This is necessary so that tooling can detect that master no longer can receive major changes. next automatially becomes a minor by default, unless explicitly changed to a major again.

Paul Gschwendtner The above in blue is something I'm not 100% sure about. I'd love input on this. Instead of always defaulting to a minor here (and not incrementing the version), we could prompt for the "next" version type, but that would require us to know beforehand whether next release-train is a major or minor. The alternative, as per above is that we use a special version value that tells the release tooling and merge script that only minor changes can land. A concern with incrementing to the next minor or major directly is that it would mean that we need to publish it directly, no?

With the active feature-freeze release-train, consecutive next pre-release's can be cut, or the version can be bumped after the feature-freeze period (could be enforced) to a release-candidate. While a feature-freeze/release-candidate is active, no pre-releases can be cut for next (master).

Cutting a feature-freeze next pre-release

As outlined in the previous section, it is possible to cut pre-releases for release-trains in feature-freeze. These releases would always go into the next NPM dist-tag. Version would need to be incremented to the next pre-release number within the feature-freeze branch.

The changelog would need to be cherry-picked into the master branch.

Cutting a release-candidate

A release-candidate can be cut for release-trains in feature-freeze or already in release-candidate phase. If a release candidate is cut for a feature-freeze branch, the version is updated from -next to -rc.0 and the RC is published to NPM.

If the version-branch is already in feature-candidate phase, the pre-release number is incremented and the new RC is published to NPM. Releases for release-candidates will always be tagged with next NPM dist tag.

The changelog would need to be cherry-picked into the master branch.

Cut stable major or minor

Depending on the type of release-train that corresponds to the active release-candidate version-branch, a non pre-release major or minor is being released. The type of release-train can be determined by checking if the version within the RC branch matches N.0.0-rc.<..>.

The version is updated so that the pre-release label is removed. e.g. 10.0.0-rc.2 becomes 10.0.0. This is done by the release tooling as part of the Staging and Releasing phases. Also note that the release will be tagged as part of the latest NPM dist tag. The changelog would need to be cherry-picked into the master brnach.

The latest release-train (i.e. the patch branch) becomes inactive as the RC branch becomes the new patch branch. Note that the previous patch branch could certainly remain active 12 months longer for LTS in case a stable major has just been cut.