# 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).

> [color=blue] 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.

> [name=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.