Creating a new release

See Upgrading to a New Release for an overview of CiviForm release practices.
Releases are created weekly by the on-call engineer on Wednesday before 12pm Pacific Time. The on-call engineer may use the production meeting time to create the release if desired. Out-of-schedule releases may be created if requested by a civic entity (e.g. for an urgent bugfix).
New releases go through a QA process that takes them from a draft state to fully published. The QA process is best-effort for official release images, and may be skipped if resources are not available.
Creating a new release
1. Find the most recent commit that is passing CI for all staging environments:
Find the commit SNAPSHOT id from one of the following, and extract the SHA from it. The SHA is the middle item in the SNAPSHOT-sha-hash ID. For example for SNAPSHOT-fa971bb-1666156765 ID the commit SHA is fa971bb.
NOTE: If the last successful snapshot for ALL environments is not the most recent one, contact a Seattle software engineer to request that they deploy the release candidate to their staging environment.
From Deployment-bot
Check the #ci Slack channel for the latest successful SNAPSHOT for AWS, Seattle, and Azure. This offers a history of previous auto pushes too.
From Staging servers
On the running servers inspect the DOM tree for <head><meta name="civiform-build-tag">. Its content attribute will only show the current SNAPSHOT for each though.
​staging-azure​
​staging-AWS​
​Seattle staging​
2. Create a New Draft Release
Before proceding you'll need to determine the Commit SHA and the next Release number.
Commit SHA
This is the middle item in the SNAPSHOT-sha-hash ID from Step 1.
Release number
Release number is based on the semver format.
Review the version number from the last release and use the rules defining version numbers to determine the new release number.
Make sure to include the 'v' prefix.
Discuss with the dev team before changing the major version number.
With those values create the draft release with one of the following options.
Option 1: Via GitHub Actions
[Step 1 & 2] Navigate to the Create Release GitHub Action.
[Step 3] Click the "Run workflow" button
Supply the Commit SHA and Release number values
[Step 4] Click the "Run workflow" button
create-release
Option 2: Manually
Setup:
Login to docker as the civiform user. If you don't have the password ask the #github-maintainers Slack channel
Generate a GH access token and provide it as documented.
When ready run create-release script:
bin/create-release SHA vNumber
If the script fails due to missing requests library. Try the following:
python3 -m ensurepip
pip3 install requests --user
The release script will then:
1.Validates the commit SHA is a commit on main and RELEASE_NUMBER matches the convention
2.Tags the git commit with the release number, annotated with description that includes the email address of the release caller, and pushes it to github
3.Pulls the existing server image from Docker Hub (identified by the commit SHA), tags it with the release number and pushes it to Docker Hub
4.Calls the GitHub API to create a new draft release
5.Prints the GH URL to the draft release
3. Edit the generated draft release
Follow the GitHub URL to the draft release printed at the end of the bin/create-release script step from the previous step, or navigate to the repo's releases page and find the new draft release.
Next, edit the release notes to include the following:
Description of fixed bugs
Description of new features
Database schema changes
Other stateful changes (such as stored file key name schema)
API version changes and deprecation notices
New configuration values
Infrastructure changes
Dependency changes (for the server only) including new, removed, and version updates
Every pull request that is relevant to the release should have a Release notes section in its description, use this if the autogenerated description for a given PR is not adequate.
4. Notify QA of the new release candidate
Message Matthew Sprenke (City of Seattle) in the #release-discussion channel on Slack, notifying QA that a new release candidate is ready for review. Make sure to do this AFTER Seattle has deployed the release candidate to staging if it is not the most recent snapshot.
A new draft release vX.X.X is ready for testing. Release notes can be found here: [INSERT LINK TO GITHUB DRAFT RELEASE HERE].
Draft release is available on the following stagings:
https://civiformstage.seattle.gov/
https://staging-aws.civiform.dev/
​
Please perform necessary QA checks before EOD Wed [INSERT DATE] PT time. If you find any issues with the release - reply to this announcement.
​
Folks to notify: @Matthew Sprenke
Wait until Matthew provides feedback on the release to proceed to step 5, do not proceed if he reports any blocking issues with the release candidate.
If Matthew is not available, recruit engineers, PMs, and other contributors to evaluate the release candidate. Direct them to specific areas of interest based on the release notes and the QA test plan.
5. Publish the release notes and email all stakeholders
Once the release notes are looking good, publish the draft notes (click the edit button and then "Publish" at the bottom of the screen) and then email the release notes to [email protected] and [email protected]

Last modified 2mo ago