Creating a new release
Releases are created weekly by the on-call engineer on Wednesday before 12pm. 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:
With those values create the draft release with one of the following options.
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
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.