New releases of the Mongo Shell project are created primarily on demand or when a bunch of worthy features or fixes is available. There is no fixed cycle for publishing new releases right now.
Execute the following steps to publish a new release:
- Ensure there is a Jira Release ticket in the
MONGOSHproject for the new release and move it to In Progress. - Verify that the Jira tickets you expect to be released are correctly mapped to the Release ticket. Add any additional required documentation to the release ticket.
- Trigger the draft release by running:
Follow the instructions and ensure that the new draft tag to be created matches the expected release version.
npm run release draft - Wait for Evergreen to finish the build and complete the draft stage.
Repeat step 3 if there are any additional changes that need to be part of the release. - Trigger the publication of the release by running:
Follow the instructions and verify the inferred release version is correct.
npm run release publish - Wait for Evergreen to finish the publication stage.
- Close the Jira ticket for the release, post an update in the
#mongoshSlack channel and ping the docs team.
Typically, a release is always created from the main branch (currently main). The only exception are patch releases, i.e. when we need to fix an issue for an already published, already superseeded release. Patch releases are created from release branches that match the following pattern:
release/v[0-9]+\.[a-zA-Z0-9]+\.[a-zA-Z0-9]+
Possible values for a release branch are:
release/v0.8.1release/v0.8.xrelease/v0.x.y
See the following image for a general overview on how we handle these branches and the corresponding tags.
We use two different types of tags for the automated release process: draft and release tags. A release tag has the form v<major>.<minor>.<patch>, e.g. v0.8.0. A draft tag is v<major>.<minor>.<patch>-draft.<draft>, e.g. v0.8.0-draft.0.
Draft tags are used to trigger the automated release process. Every draft tag in the end leads to the generation of potentially distributable packages with compiled binaries.
Release tags are used to trigger the publication of a release and its corresponding distributable packages. A release tag must referenced the commit with the most recent draft tag for that release version (example: v0.8.0 must reference the commit with the highest v0.8.0-draft.x tag).
The automated release process for publication of a release will re-use the compiled binaries and packages that were created in the most recent draft tag. Thus, every release tag requires a prior draft tag to be present. The release automation process is handled by Evergreen.
The Mongo Shell project uses Evergreen for Continuous Integration and the release automation process described above. Follow Evergreen Build to see the waterfall for the Mongo Shell project.
For full details on the project's configuration see the Evergreen configuration file .evergreen.yml.
Evergreen builds and patches are triggered in multiple ways. The Mongo Shell project is setup to be triggered by:
- New commits on the main branch (currently
main, i.e. waterfall builds - New Pull Requests against the main branch on GitHub (i.e. patches)
- A new tag matching
v0.0.0-draft.0is pushed on the main or a release branch (i.e. a draft build is triggered) - A new tag matching
v0.0.0is pushed on the main or a release branch (i.e. a release is to be published)
The following image shows an overview on the different stages of the build in Evergreen.
The Tests stage contains multiple tasks:
- Checks that the code conforms to linting guidelines
- Runs all unit tests in a matrix configuration (Node v12 and v14, server versions 4.0 / 4.2 / 4.4 / latest) as needed per package. Note: Coverage is only computed after running all unit tests and combining results.
- Runs additional verification tests (VS code integration and connectivity tests)
The Compile stage produces an executable binary (leveraging boxednode) for every target platform and uploads it to the Evergreen S3 bucket for later user.
The Package stage depends only on Compile to complete successfully and not on Tests to reduce overall execution time. It will download the binary executable, package it into a distributable archive (e.g. a .deb package or a .zip file) and re-upload that to Evergreen S3 for every target platform.
The E2E Tests stage depends on the Compile stage to complete successfully. It will download the binary executable of the Compile stage from Evergreen S3 and run JavaScript-defined E2E tests with it on all target platforms that we support.
The Smoke Tests stage depends on the Package stage to complete successfully. It will download the packaged distributable and run it via Docker or SSH on different target operating systems to verify that the distributable can be installed and works as expected.
The Draft stage depends on all three stages Tests, E2E Tests and Smoke Tests to complete successfully. Draft will download all distributable packages created in the Package stage and re-upload them to:
- MongoDB Download Center: uploads to the corresponding S3 bucket without publishing the Download Center configuration.
- GitHub Release: creates a new draft release if there is none for the release version yet and either uploads or removes and re-uploads the distributable packages. It will also generate a changelog and add it to the draft release.
The Publish stage is independent from all other stages. As mentioned at the beginning when a release tag is pushed to the repository it will directly trigger the Publish stage. It will do the following things:
- Use
curatorto transfer the distributable packages from Evergreen S3 to the MongoDB PPAs. - Upload the full configuration to Download Center so the release is available there.
- Promote the GitHub release created in Draft to a published release.
- Publishes the npm packages.
- Creates a new PR for the official Homebrew repository to update the
mongoshformula.
The package has two major purposes:
- Custom build commands to handle the stages outlined above
- Provide easy helpers to trigger the release process
See index.ts for the main entry point on the different commands.