Creating a new release
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.
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-1666156765ID the commit SHA is
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.
Check the #ci Slack channel for the latest successful SNAPSHOT for AWS, Seattle, and Azure. This offers a history of previous auto pushes too.
On the running servers inspect the DOM tree for
<head><meta name="civiform-build-tag">. Its
contentattribute will only show the current SNAPSHOT for each though.
Before proceding you'll need to determine the Commit SHA and the next Release number.
This is the middle item in the SNAPSHOT-sha-hash ID from Step 1.
- 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.
- [Step 3] Click the "Run workflow" button
- Supply the
- [Step 4] Click the "Run workflow" button
- Login to docker as the civiform user. If you don't have the password ask the #github-maintainers Slack channel
bin/create-release SHA vNumber
If the script fails due to missing
requestslibrary. 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
Follow the GitHub URL to the draft release printed at the end of the
bin/create-releasescript 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 notessection in its description, use this if the autogenerated description for a given PR is not adequate.
Message Matthew Sprenke (City of Seattle) in the
#release-discussionchannel 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:
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.
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]