Skip to content
This repository was archived by the owner on Jan 30, 2024. It is now read-only.

Release Process

Jump to bottom
Mark Vogelgesang edited this page Apr 20, 2023 · 25 revisions

Release Process

Principles

  1. Follow well-established versioning practices
  2. Provide detailed notes for each release
  3. Encourage contributions and thank contributors for their hard work

Versioning

Semantic versioning is a method of numbering release versions that aims to help users understand the implications of upgrading from one release to another. Semantic version numbers take the form major.minor.patch, where:

  • Bug fixes increment the patch number (e.g. 1.0.0 to 1.0.1)
  • New features increment the minor number and reset patch (e.g. 1.0.1 to 1.1.0)
  • Changes to the public API (breaking changes) increment the major version and reset minor and patch (e.g. 1.1.2 to 2.0.0)

The Public API

In most software projects, the "public API" corresponds to a single set of programming constructs, such as public classes or functions. For example, any of the following should trigger a major version increment:

  • Removing any Aura Attributes or Design Attributes from a Theme Layout or Component
  • Upgrading to a new major version of the US Web Design System
  • Utilization of any newly released Salesforce features or functionality that are deployed three times per year. For example, the Salesforce Summer '20 release (v49) is due out in July. A new major version would be created any component in this code base took advantage of the new Override Standard Actions feature

Release process

⚠️ In these docs, {{ version }} should always be replaced with the semantic version number, i.e. 1.2.1 ⚠️

Creation of a Salesforce-hosted package has been discontinued. Please install from source here instead.

Cadence

We aim to produce a new minor version on a quarterly basis. Should there be an influx of features or changes, we may produce new versions more frequently.

Release Pre-Steps

Set local $releaseVersion variable to the new semantic version number. Wherever possible, this release process aims to use the local variable as a means for preventing errors.

releaseVersion=x.x.x
echo $releaseVersion

NPM Dependencies

npm update -g
npm install
sfdx update
  • Output from NPM should indicate if there are any vulnerabilities. Note this in the log as it will be used in the release notes.

Dependencies and security

0 vulnerabilities in regular dependencies 0 high vulnerabilities in devDependencies (development dependencies)

Theme Definition

  • Update the version number listed in the Community Theme Definition src/communityThemeDefinitions/USWDS_Lightning_Community.communityThemeDefinition
  • <masterLabel>USWDS {{version}}</masterLabel>

README.md

  • Check README.md to refer to correct USWDS version
  • Update screenshots as needed

Prettier

  • Run Prettier against all files
prettier --write .

Commit Changes and Push

  • Recent changes to readme.md, communityThemeDefinition, and any updates from Prettier should be committed and pushed.

Release Candidate

Prior to publishing a new major or minor release, a release candidate branch shall be created and made available to the broader community for at least 3 weeks. Patch releases do not require a Release Candidate. By following a Release Candidate process, proposed changes allow teams at GSA and other users the ability to test functionality, provide feedback, and potentially fix bugs before a release is shipped.

Create a Release Candidate Branch (RC)

  • Determine if the version is a minor (#.#.0), or major (#.0.0) version. Note, release candidates are not created for patch releases.
  • Determine RC number. If this is the first release candidate for a given release, it is RC1. As updates are provided, increment the RC number by 1.
  • Branch off develop and use the branch name format {{ version }}-rc{{#}}.
git pull origin
git checkout -b $releaseVersion-rc{{ # }} origin/develop
  • If there's been further work on develop since branching, merge the most recent develop into the rc branch.

Release Candidate Feedback Process

Feedback should be gathered in Github issues. Where appropriate, update code and create new RC for testing.

If no major issues arise and the three week period has passed, move onto creating a Release.

Create a Release

Create the Release Branch

  • Determine if the version is a patch (#.#.#), minor (#.#.0), or major (#.0.0) version
  • Branch off develop and use the branch name format release-{{ version }}.
git pull origin
git checkout -b release-$releaseVersion origin/develop
  • If there's been further work on develop since branching, merge the most recent develop into the version branch.

Merge the Release into main

  • Push the version branch up to GitHub git push origin release-$releaseVersion
  • Open a pull request from your release branch into main with the title "Release {{ version }}."
  • List the key changes in the release in the pull request description. See the v1.0.0 pull request for an example.
  • Have at least one team member approve the pull request
  • Once the pull request is approved, merge it into main via "Rebase and Merge".

Create the Release in GitHub

  • Checkout the main branch and fetch latest merge from origin git pull origin main
  • With the main branch checked out, zip entire directory contents to build the zip package. This commmand should be run from project root. Name package uswds-sf-lightning-community_v{{version}}.zip

zip -r uswds-sf-lightning-community_v$releaseVersion.zip .github/ .tours/ .vscode/ examples/ img/ src/ test/ .forceignore .gitignore .npmrc .nvmrc .prettierignore .prettierrc CODE_OF_CONDUCT.md CONTRIBUTING.md INSTALLATION.md LICENSE.md package.json package-lock.json README.md sfdx-project.json

  • Generate SHA256 of zip package shasum --algorithm 256 uswds-sf-lightning-community_v$releaseVersion.zip
  • In GitHub releases select Draft a new release
  • Add the tag: v{{ version }}
  • Use target: main
  • Add release notes to the body
    • this should be a compilation of notes from pull requests and issues that contributed to the release. Easy way to do so is git log {last tag}..HEAD eg git log v1.0.0..HEAD
    • Sections to include
      • Description and features. Note any bugs addressed
      • Contributors
      • USWDS Version
  • Create Website Manager-focused notes for the release. These notes should include the following:
    • Release Number
    • Features that are site manager facing
  • Have at least one team member review the release notes
  • Select Publish release

Merge main back into develop

  • Open pull request from main to develop, Rebase and Merge
  • Ensure that the develop branch is using the latest version git checkout develop git pull
    • Note: if squashing commits, merge release-{{ version } into develop

Post Release

Email interested parties that the release is live.

Special thanks to the US Web Design System team who's Release Process helped guide this effort.

  • Spotlight
    • List and links of sites using the theme.

For Developers

Repo Maintainers

Users

Clone this wiki locally