These steps describe releasing the libmongocrypt C library (not the language bindings).
Version numbers of libmongocrypt must follow the format 1.[0-9].[0-9] for releases and 1.[0-9].[0-9]-(alpha|beta|rc)[0-9] for pre-releases. This ensures that Linux distribution packages built from each commit are published to the correct location.
Snyk and Silk are used to satisfy vulnerability scanning requirements of DRIVERS-714. Prior to releasing, ensure necessary reported vulnerabilities meet requirements described in: MongoDB Software Security Development Lifecycle Policy.
Go to Snyk and select the dev-prod
organization. If access is needed, see Snyk Onboarding. Check the CLI target named mongodb/libmongocrypt
. The CLI targets may be identified by this icon: . There are reference targets for each tracked branch:
Update the Snyk reference target tracking the to-be-released branch. For a patch release (e.g. x.y.z), check-out the rx.y
branch and update the rx.y
reference target. For a minor release (e.g. x.y.0), check out the master
branch update the master
reference target.
Run cmake
to ensure generated source files are present:
cmake -S. -Bcmake-build -D BUILD_TESTING=OFF
cmake --build cmake-build --target mongocrypt
Print dependencies found by Snyk and verify libbson is found:
snyk test --unmanaged --print-dep-paths
Copy the organization ID from Snyk settings. Create the new Snyk reference target to track the newly created release branch:
snyk auth
snyk monitor \
--org=$ORGANIZATION_ID \
--target-reference="<rx.y or master>" \
--unmanaged \
--remote-repo-url=https://github.com/mongodb/libmongocrypt.git
Check the updated reference targets in Snyk for detected vulnerabilities.
Get credentials for Silk from the drivers/libmongocrypt
vault in AWS Secrets Manager.
Download the Augmented SBOM using:
./.evergreen/earthly.sh \
--secret silk_client_id=${silk_client_id} \
--secret silk_client_secret=${silk_client_secret} \
+sbom-download \
--out cyclonedx.augmented.sbom.json \
--branch <branch>
Check the contents of the "vulnerabilities" field (if present) in the Augmented SBOM.
Do the following when releasing:
-
If this is a feature release (e.g.
x.y.0
orx.0.0
), follow these steps: Creating SSDLC static analysis reports. -
Check out the release branch. For a release
x.y.z
, the release branch isrx.y
. If this is a new minor release (x.y.0
), create the release branch. -
Update CHANGELOG.md with the version being released.
-
Ensure
etc/purls.txt
is up-to-date. -
Update
etc/third_party_vulnerabilities.md
with any updates to new or known vulnerabilities for third party dependencies that must be reported. -
If this is a new minor release (e.g.
x.y.0
):- Update the Linux distribution package installation instructions in README.md to refer to the new version
x.y
. - Update the libmongocrypt-release Evergreen project (requires auth) to set
Branch Name
torx.y
.
- Update the Linux distribution package installation instructions in README.md to refer to the new version
-
Commit the changes on the
rx.y
branch with a message like "Update CHANGELOG.md for x.y.z". -
Tag the commit with
git tag -a <tag>
.- Push both the branch ref and tag ref in the same command:
git push origin master 1.8.0-alpha0
orgit push origin r1.8 1.8.4
- Pushing the branch ref and the tag ref in the same command eliminates the possibility of a race condition in Evergreen (for building resources based on the presence of a release tag)
- Note that in the future (e.g., if we move to a PR-based workflow for releases, or if we simply want to take better advantage of advanced Evergreen features), it is possible to use Evergreen's "Trigger Versions With Git Tags" feature by updating both
config.yml
and the project's settings in Evergreen
- Push both the branch ref and tag ref in the same command:
-
Ensure the version on Evergreen with the tagged commit is scheduled. The following tasks must pass to complete the release:
upload-all
windows-upload-release
- All
publish-packages
tasks.- If the
publish-packages
tasks fail with an error like[curator] 2024/01/02 13:56:17 [p=emergency]: problem submitting repobuilder job: 404 (Not Found)
, this suggests the published path does not yet exist. Barque (the Linux package publishing service) has protection to avoid unintentional publishes. File a DEVPROD ticket (example) and assign to the team called Release Infrastructure to request the path be created. Then re-run the failingpublish-packages
task. Ask in the slack channel#devprod-release-tools
for further help withBarque
orcurator
.
- If the
-
Create the release from the GitHub releases page from the new tag.
- Attach the tarball and signature file from the Files tab of the
windows-upload-release
task. Example. - Attach the Augmented SBOM file. Download the Augmented SBOM using:
For a new minor release, use
./.evergreen/earthly.sh \ --secret silk_client_id=${silk_client_id} \ --secret silk_client_secret=${silk_client_secret} \ +sbom-download \ --out cyclonedx.augmented.sbom.json \ --branch <branch>
master
for--branch
. For a patch release, use the release branch (e.g.rx.y
). Secrets can be obtained from AWS Secrets Manager underdrivers/libmongocrypt
. - Attach
etc/third_party_vulnerabilities.md
to the release. - Attach
etc/ssdlc_compliance_report.md
to the release.
- Attach the tarball and signature file from the Files tab of the
-
If this is a new minor release (e.g.
x.y.0
):-
File a DOCSP ticket to update the installation instructions on Install libmongocrypt. (Example)
-
Create a new Silk asset group. Use the newly created release branch (e.g.
rx.y
) as the--branch
argument:./.evergreen/earthly.sh \ --secret silk_client_id=${silk_client_id} \ --secret silk_client_secret=${silk_client_secret} \ +silk-create-asset-group \ --branch <branch>
-
Create a new Snyk reference target. The following instructions use the example branch
rx.y
:Run
cmake
to ensure generated source files are present:cmake -S. -Bcmake-build -D BUILD_TESTING=OFF cmake --build cmake-build --target mongocrypt
Print dependencies found by Snyk and verify libbson is found:
snyk test --unmanaged --print-dep-paths
Copy the organization ID from Snyk settings. Create the new Snyk reference target to track the newly created release branch:
snyk auth snyk monitor \ --org=$ORGANIZATION_ID \ --target-reference=rx.y \ --unmanaged \ --remote-repo-url=https://github.com/mongodb/libmongocrypt.git
Snyk reference targets for older release branches may be removed if no further releases are expected on the branch.
-
Update the Github Webhook to include the new branch.
- Navigate to the Webhook Settings.
- Click
Edit
on the hook forhttps://githook.mongodb.com/
. - Add the new release branch to the
Payload URL
. Remove unmaintained release branches.
-
-
Make a PR to apply the "Update CHANGELOG.md for x.y.z" commit to the
master
branch. -
Update the release on the Jira releases page.
-
Record the release on C/C++ Release Info. This is done to meet SSDLC reporting requirements.
-
Add a link to the Evergreen waterfall for the tagged commit to libmongocrypt Security Testing Summary.
Submit a PR to update the Homebrew package https://github.com/mongodb/homebrew-brew/blob/master/Formula/libmongocrypt.rb. (Example). If not on macOS, request a team member to do this step.
If you are not a Debian maintainer on the team, request a team member to do the steps in this section.
Refer to the Debian steps.
For a minor release (e.g. x.y.0), submit a merge request to the extrepo-data project in Debian to update the PPA. The change would look something like this:
diff --git a/repos/debian/libmongocrypt.yaml b/repos/debian/libmongocrypt.yaml
index 609dc0b..f7530a9 100644
--- a/repos/debian/libmongocrypt.yaml
+++ b/repos/debian/libmongocrypt.yaml
@@ -4,7 +4,7 @@ libmongocrypt:
source:
Types: deb
URIs: https://libmongocrypt.s3.amazonaws.com/apt/debian
- Suites: <SUITE>/libmongocrypt/1.11
+ Suites: <SUITE>/libmongocrypt/1.12
Components: main
Architectures: amd64 arm64
suites: