Release - grommet/grommet GitHub Wiki

This wiki page is documenting the Grommet release process:

Contents

• Pre-requisites
• Release preparation
• Publishing release via Github
• Confirmation
• Last steps

Pre-requisites

1. Find yourself a buddy to share the release process with, another per of eyes on the process could be priceless, educating for you both, and much more fun :)
2. Make sure you have GitHub admin permissions on the grommet repository.
3. Publishing to NPM is done via "Publish" from GitHub. You will need Admin permissions on the grommet repository to be able to push directly to master.
4. Know the Semantic Versioning rules to determine whether the release is a major/minor/hotfix release. NOTE: Grommet follows an inspired flavor of Semantic Versioning where MAJOR.MINOR.PATCH are incremented:
   • MAJOR when API is significantly changed.
   • MINOR when adding new, notable, backwards compatible features. Communicates to users "you might be interested in checking out these new features."
   • PATCH when changes are fixes or minor enhancements which are likely to go unnoticed by most.
5. Make sure you are familiar with all the background content available on this recording.
   • 0:00-3:20 | Introduction + considerations for when to release and what to include.
   • 3:20-7:00 | Release notes, introduction.
   • 7:00-11:50 | Release notes, reviewing commits.
   • 11:50-12:30 | Versioning releases.
   • 13:00-14:10 + 21:00-24:40 | Release notes, writing conventions.
   • 14:15-15:45 | Quality assurance checks.
   • 16:00-21:00 + 24:40-31:25 | Incrementing version in package.json & committing.
   • 24:45-36:20 | Creating release tag & notes.
   • 31:25-37:30 | Build production & pack assets.
   • 38:10-38:45 | Publish release.
   • 38:45-43:53 | Confirm release successfully deploys.
6. Go over all recent commits from the previous release and summarize notes from each commit relevant to production.
7. Write the names of all the contributors that had contributed to the release on a side list - you'll need it for the announcement.
   • Use contributor's Slack handle if available, otherwise use GitHub username.
8. Check that documentation updates were added to grommet-site for commits that require documentation changes.
9. For any new props or components check that they have been added to grommet-designer.

Let's Get Started

1. Open your local clone of grommet - make sure it is all cleaned up without any local changes on your master branch.

2. git pull - make sure you are up to date with the master branch.

3. Deploy storybook locally to make sure things are compiling/working as expected - without any warnings and errors.

   • Interact with stories for each component. Pay particular attention to components which are included in the release notes.
   • Test stories across Firefox, Safari, and Chrome browsers.
   • If you encounter an issue, identify the commit causing the behavior. Depending on the issue and commit, you may need to work with the contributor, another developer, etc. to resolve the issue prior to proceeding.

4. In package.json update the version following Grommet's Semantic Versioning conventions.

5. Add and commit directly to master with message Updated vX.Y.Z (i.e., Updated v2.17.0) - This is the only time we directly commit to the master branch (EVER 😉).

6. git push the commit of package.json - to play it safe, only continue to the next step after CircleCI finishes without any errors/warnings.

7. Check that the push to master has passed in CircleCI.

8. Create GitHub tag git tag vX.Y.Z - One has to include the “v” on the tag, so cicrcleci/github will register it properly.

9. After CircleCI passes, push tag using git push origin vX.Y.Z.

10. Run locally yarn build to create the production files.

    • Not relevant to releasing grommet-theme-hpe. Skip this step.
    • Not relevant to releasing grommet-icons. Skip this step.

11. Run locally npm run pack to create the license files.

    • Not relevant to releasing grommet-theme-hpe. Skip this step.
    • Not relevant to releasing grommet-icons. Skip this step.
    • By the end of this flow, there should be 2 files created on your local environment, a .json and .tgz files for the deployment and licensing. You will use these assets when publishing the release.

On Github

1. Create the release from the draft that should have been created automatically on the GitHub releases page.
2. Edit the draft, and paste release notes to it.
   • Release title is the same as the version tag.
   • Wrap propNames in backticks(`).
   • Capitalize component names (e.g. MyComponent).
   • Make a component or topic its own category/group if it has multiple contributions against it. Otherwise, place under "General".
   • Write notes using past tense (e.g. added, fixed, enhanced, changed, improved).
   • 4:50-7:00 | Video discussion
3. Drag and drop the license files (.json and .tgz) to the assets of the release
4. Hit publish (Congrats!!)

Confirmation

Confirm the release was successful by the following:

1. Confirm latest version is displayed on NPM.
2. Confirm the latest version is available on CodeSandbox
   • NOTE: CodeSandbox UI can take time to sync with NPM. Change version manually in package.json if it doesn’t show up in the dropdown.
   • Confirmation may be done by testing functionality that is only relevant for this release on the code sandbox and see it works as expected.

Last Steps

1. Update the CodeSandbox template to use the latest version of Grommet.
   • Note: must have permission to login to the grommetux Github account to do this.
2. Update Change Log by pasting the release notes in (https://github.com/grommet/grommet/wiki/Change-Log)
3. Go to the grommet-site repo
   1. git pull
   2. Remove any 'stable' notifications from props or components.
   3. Remove yarn.lock and upgrade dependencies so that the docs on the site are up to date and aligned with the release. rm yarn.lock && yarn cache clean && yarn install
   4. git add yarn.lock, git commit and git push
   5. Verify grommet-site builds and deploys successfully.
4. Post an announcement in #announcements on Grommet Slack, while thanking the contributors of the release in the announcement. In addition post release announcements in the hpe-design-system channel and the ccs-ui-dev channel. These announcements should not include the contributors.
5. Post a release announcement on Twitter. - We no longer have access to the Grommet twitter account. Skip this step for now.
6. Point to the newly released version of Grommet and generate a SBOM using Revenera and load it into VTN.
7. Close the original github issue/ticket for the release, and file a new issue for the following month.
8. Now that the release is complete, check grommet dependencies and upgrade to the latest versions on the yarn.lock file. It is best if dependencies will be upgraded right after the release to give it time to sit on stable and making sure the packages upgrade don't break any existing behavior for the next release. As we wait with upgrading dependencies the risk and efforts are usually higher.

This release process also works for the repositories of grommet-icons and grommet-theme-hpe.