Improved releases with Beachball

[chrisdholt]

Overview

This spec proposes a new workflow for publishing and the addition of "Beachball", a new package to manage semantic versioning, changelogs, and releases. This work is to help coordinate with a larger plan of releases being addressed by @awentzel with #3872.

Background

Currently, we use Lerna for all things related to package publishing using the conventional commits flag. Currently all of our publishing is manual and is scheduled on a regular cadence of every other week. Lerna uses the commit message, which in some cases is either the commit message itself, or the Github pull request title. The inconsistency here is just one of several issues which have created headaches. We've talked quite a bit in the past around improved changelogs, better control over changelog messages, automated releases, wiring up to Github releases, and other improvements. Beachball will not only meet our requirements but add additional functionality, more control, and improved workflow.

Non-goals

This work is not intended as a wholesale replacement for Lerna.

Dev Workflow

Without any configuration, beachball fits into your workflow. When you have made some commits to your branch, simply fire up beachball change to generate change files. During PR review and feedback loops, your colleagues might remind you to modify your change file descriptions or change type. This then gets merged to the target branch (e.g. master). After this, beachball publish is either called by a continuous integration (CI) system or manually by a developer.

Using Beachball

In most cases, a single PR would address a single change and include a single file. The workflow for that would look as follows:

1. Feature work is done
2. Prior to pushing, developer runs yarn change to generate a change file
3. Pull request is created
4. Change file is included as part of the Pull Request where it is subject to code review

Sometimes, additional changes may be needed to introduce new features. Those may require changes to other packages which would necessitate a changelog entry. Beachball handles this with ease and multiple change files can be included to handle scenarios like this.

yarn change workflow
When yarn change is run, the following processes run within the users terminal:

1. Check for changes
   • Beachball checks for changes against "upstream/master"
   • Identifies any changes within packages
   • If no changes are found, exists
2. If changes are found, a prompt is presented to describe the changes. Recent commits are listed so a user can correlate their changes to previous commit messages. Alternatively, a user may begin typing to provide a custom message.
3. git commits the change

Example change file:

{
  "type": "minor",
  "comment": "add history and a way to retrieve history from the message system",
  "packageName": "@microsoft/fast-components-react",
  "email": "[email protected]",
  "dependentChangeType": "minor",
  "date": "2020-09-01T19:10:06.323Z"
}

Helpful links:

• bump-algorithm
• change files
• verison groups

Publishing via CI

Per Beachballs documentation:

Publishing automates all the bumping and synchronizing of package versions in git remotes as well as the npm registry. The steps taken by the publish command are designed to be run so that it minimizes the chances of failure by doing validation upfront.

When publish is called, the following three things will happen:

• All change files are deleted (more than one change file can be checked in before a single publish happens)
• Versions are bumped, checked in locally and pushed remotely
• npm packages are published to a public or private registry

Publishing steps

By publishing, Beachball performs the following tasks:

1. Validate that there are no local changes
2. Validate that the versions to be bumped are in fact available in the npm registry
3. Bumps the package versions
4. Generate package changelog files
5. Revert all these changes
6. Fetch latest git changes on the remote target branch
7. Perform the exact same thing in steps 3 & 4
8. Push these changes back to the remote target branch

Automated nightly publish

As part of this implementation, I would propose that we incorporate to a nightly publish using Beachball. By automating a nightly publish, we can provide quicker turnarounds for bug fixes and features with a regular rhythm without disrupting anyone's workflow to hold for publishing. Additionally, contributors and consumers of FAST know exactly when they can expect the changes to be published.

I think a key benefit here would be a removal on the "rush" to get things in for a release. The fact that changes can publish the evening it goes in means that there's not a negative consequence of waiting an extra day or two to ensure that we've validated a given control or feature.

Perform as a separate work issue, post Beachball Implementation

Connecting to Github Releases

While Beachball doesn't natively integrate with Github releases, the Fluent UI team has created some scripts to facilitate this integration. That implementation could be leveraged in part or in whole to replicate the functionality.

Linking the release version to a Pull Request

There is a bot provided to teams at Microsoft of OSS projects which supports things like tagging releases in PR's and hooking other automation in. I've reached out to the team and inquired about the onboarding process so we can launch that in coordination with the nightly releases.

[EisenbergEffect]

Two things I wanted to note:

• Have we considered how this might affect community contributors? I assume we'll update the docs to add the additional step of running yarn change. However, I do expect folks to forget that or not know about it. Does the Fluent team have any learnings from their community behavior around this?
• I want to highly recommend that we publish the nightly builds to an npm dev channel, not to the main release channel. Releasing nightly to the main channel would be quite destabilizing I think. So, I'd recommend having at least two release trains, the slow train that is stable and undergoes all of our current quality validation, and the fast train that ships nightly as long as tests pass. As long as we have the nightly release, we could drop back to once per month for the stable release.

[chrisdholt]

Great questions, thoughts/answers below:

• Have we considered how this might affect community contributors? I assume we'll update the docs to add the additional step of running yarn change. However, I do expect folks to forget that or not know about it. Does the Fluent team have any learnings from their community behavior around this?
  Yes, I blanked as I was going to submit this and felt there was something that was missing - this was it! I think one easy way would be as you mention to update the docs with that additional step.

Fluent has a fairly straight forward PR template which calls it out, and I think that helps as well:

Pull request checklist

 [ ] Addresses an existing issue: Fixes #0000
 [ ] Include a change request file using `$ yarn change`

I believe there is also a check command we can run to check for any missed changes, and we can at that time fail an optional build if we choose to. While there is an additional step here, I think it's a better experience overall for contributors for a couple of reasons. Currently we rely on correct commit messages and we've seen trouble with automated attempts to lint those - sometimes bad messages make it through, sometimes good messages fail. In this case, the changelog message is under control of the contributor AND checked in with the change. There isn't any shadowed or implicit logic to understand what is happening - nothing is really left to the imagination here - which is currently the case.

The other bit is that if a change file is missing, it's fairly easy to run it again locally, commit that file, and push the changes. If there is no file, we can either choose to always require one, or we can treat it just like a chore. No changelog message will be created and no publish will take place if that's the only change.

The one thing this does require is for collaborators and codeowners to know 2 things:

1. Does this impact published packages?
2. Does this include a change file?

That's a fairly low bar to be honest, and it really only requires us to do that which we've already committed to - be thorough in our reviews :).

A massive benefit in my opinion, is that we no longer need to police actual commit messages or github PR titles.

• I want to highly recommend that we publish the nightly builds to an npm dev channel, not to the main release channel. Releasing nightly to the main channel would be quite destabilizing I think. So, I'd recommend having at least two release trains, the slow train that is stable and undergoes all of our current quality validation, and the fast train that ships nightly as long as tests pass. As long as we have the nightly release, we could drop back to once per month for the stable release.

I agree on this, but I think it's going to require some investigation on our part. My recommendation here would be a staged approach. First, swap beachball for publishing. Second, setup the nightly automated release.

[EisenbergEffect]

Sounds good.

[dzearing]

The .github\PULL_REQUEST_TEMPLATE.md file mentions something like:

#### Pull request checklist

- [ ] Addresses an existing issue: Fixes #0000
- [ ] Include a change request file using `$ yarn change`

So at least contributors will think about it before contributing.

[EisenbergEffect]

I'm about to revamp all our issue and PR templates, so I'll make sure we've got this in the new versions. Thanks @dzearing 😄

[chrisdholt]

@EisenbergEffect good news - @kenotron just enabled canary builds with Beachball here microsoft/beachball#406 !!!

Thanks @kenotron, what timing!

[awentzel]

Blocked awaiting Beachball's Metadata feature to fully support how we'd want to use beachball.

[awentzel]

#4018 implements plumbing in PR 2 of 2 in preparation for new beachball feature. Once this goes in, final testing and configuration would need performed to verify. Then metadata could be implemented as a final step when the feature is available.

[EisenbergEffect]

Let's not close until we get #4018 merged.

[awentzel]

This work has been completed. The additional 'metadata' work will be completed during #4626 work in the future.