Skip to content

releasing.md

Latest commit

 

History

History
159 lines (130 loc) · 10.1 KB

releasing.md

File metadata and controls

159 lines (130 loc) · 10.1 KB

Releasing libmongocrypt

These steps describe releasing the libmongocrypt C library (not the language bindings).

Version number scheme

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.

Steps to release

Check for Vulnerabilities

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.

Check Snyk

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: CLI icon. There are reference targets for each tracked branch:

Reference Targets

Update Snyk

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 non-patch release (e.g. x.y.0), check out the master branch and 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.

Check the Augmented SBOM

Examine the Augmented SBOM from a recent execution of the sbom task in an Evergreen patch or commit build.

Evergreen CLI may be used to schedule only the sbom task:

# Ensure `-p` matches the correct Evergreen project for the current branch!
evergreen patch -y -p libmongocrypt -t all -v sbom -f

Check the contents of the "vulnerabilities" field (if present) in the Augmented SBOM.

Release

Do the following when releasing:

  • If this is a feature release (e.g. x.y.0 or x.0.0), follow these steps: Creating SSDLC static analysis reports.
  • Join the releases team on GitHub via MANA.
  • Check out the release branch. For a release x.y.z, the release branch is rx.y. If this is a new non-patch 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 non-patch 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 to rx.y.
  • Commit the changes on the rx.y branch with a message like "Release 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 or git 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
  • 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 failing publish-packages task. Ask in the slack channel #ask-devprod-release-tools for further help with Barque or curator.
  • 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 to the release as cyclonedx.augmented.sbom.json. Download the Augmented SBOM from a recent execution of the sbom task in an Evergreen patch or commit build.
    • Attach etc/third_party_vulnerabilities.md to the release.
    • Attach etc/ssdlc_compliance_report.md to the release.
  • Check out the release branch (rx.y). Generate a new unique SBOM serial number for the next upcoming patch release (e.g. for 1.13.1 following the release of 1.13.0): 
    ./.evergreen/earthly.sh +sbom-generate-new-serial-number
    Commit resulting etc/cyclonedx.sbom.json and push to rx.y.
  • Remove yourself from the releases team on GitHub via MANA.
  • If this is a new non-patch release (e.g. x.y.0):

    • File a DOCSP ticket to update the installation instructions on Install libmongocrypt. (Example)

    • 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 for https://githook.mongodb.com/.
      • Add the new release branch to the Payload URL. Remove unmaintained release branches.
  • Make a PR to to the master branch:
    • Apply changes from the "Release x.y.z" commit.
    • If this was a non-patch release (e.g. x.y.0), generate a new unique SBOM serial number for the next upcoming non-patch release (e.g. for 1.14.0 following the release of 1.13.0): 
      ./.evergreen/earthly.sh +sbom-generate-new-serial-number
      Commit resulting etc/cyclonedx.sbom.json.
  • Update the release on the Jira releases page.
  • Record the release on C/C++ Release Info. This is done to leave commentary about the process.
  • Add a link to the Evergreen waterfall for the tagged commit to libmongocrypt Security Testing Summary.

Homebrew steps

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. Request review by posting in #ask-devprod-build.

Debian steps

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 non-patch 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.12
+    Suites: <SUITE>/libmongocrypt/1.13
     Components: main
     Architectures: amd64 arm64
   suites: