Glean release process
The Glean SDK consists of multiple libraries for different platforms and targets. The main supported libraries are released as one. Development happens on the main repository https://github.com/mozilla/glean. See Contributing for how to contribute changes to the Glean SDK.
The development & release process roughly follows the GitFlow model.
Note: The rest of this section assumes that
upstream
points to thehttps://github.com/mozilla/glean
repository, whileorigin
points to the developer fork. For some developer workflows,upstream
can be the same asorigin
.
Table of Contents:
- Published artifacts
- Standard release
- Hotfix release for latest version
- Hotfix release for previous version
- Upgrading android-components to a new version of Glean
Published artifacts
- The Kotlin libraries are published to GitHub Releases and Mozilla Maven.
- Python bindings are published on PyPI: glean-sdk.
- iOS framework artifacts: GitHub Releases.
- Rust crates are published on crates.io: glean-core, glean-ffi.
Standard Release
Releases can only be done by one of the Glean maintainers.
- Main development branch:
main
- Main release branch:
release
- Specific release branch:
release-vX.Y.Z
- Hotfix branch:
hotfix-X.Y.(Z+1)
Create a release branch
- Create a release branch from the
main
branch:git checkout -b release-v25.0.0 main
- Update the changelog .
- Add any missing important changes under the
Unreleased changes
headline. - Commit any changes to the changelog file due to the previous step.
- Add any missing important changes under the
- Run
bin/prepare-release.sh <new version>
to bump the version number.- The new version should be the next patch, minor or major version of what is currently released.
- Let it create a commit for you.
- Push the new release branch:
git push upstream release-v25.0.0
- Wait for CI to finish on that branch and ensure it's green:
- https://circleci.com/gh/mozilla/glean/tree/release-v25.0.0
- You can find the TaskCluster task on the corresponding commit. See How to find TaskCluster tasks for details.
- Apply additional commits for bug fixes to this branch.
- Adding large new features here is strictly prohibited. They need to go to the
main
branch and wait for the next release.
- Adding large new features here is strictly prohibited. They need to go to the
Finish a release branch
When CI has finished and is green for your specific release branch, you are ready to cut a release.
- Check out the main release branch:
git checkout release
- Merge the specific release branch:
git merge --no-ff release-v25.0.0
- Push the main release branch:
git push upstream release
- Tag the release on GitHub:
- Draft a New Release in the GitHub UI (
Releases > Draft a New Release
). - Enter
v<myversion>
as the tag. It's important this is the same as the version you specified to theprepare_release.sh
script, with thev
prefix added. - Select the
release
branch as the target. - Under the description, paste the contents of the release notes from
CHANGELOG.md
.
- Draft a New Release in the GitHub UI (
- Wait for the CI build to complete for the tag.
- You can check on CircleCI for the running build.
- You can find the TaskCluster task on the corresponding commit. See How to find TaskCluster tasks for details.
- Send a pull request to merge back the specific release branch to the development branch: https://github.com/mozilla/glean/compare/main...release-v25.0.0?expand=1
- This is important so that no changes are lost.
- This might have merge conflicts with the
main
branch, which you need to fix before it is merged.
- Once the above pull request lands, delete the specific release branch.
- Update
glean-ffi
in the iOS megazord. See the application-services documentation for that.
Hotfix release for latest version
If the latest released version requires a bug fix, a hotfix branch is used.
Create a hotfix branch
- Create a hotfix branch from the main release branch:
git checkout -b hotfix-v25.0.1 release
- Run
bin/prepare-release.sh <new version>
to bump the version number.- The new version should be the next patch version of what is currently released.
- Let it create a commit for you.
- Push the hotfix branch:
git push upstream hotfix-v25.0.1
- Create a local hotfix branch for bugfixes:
git checkout -b bugfix hotfix-v25.0.1
- Fix the bug and commit the fix in one or more separate commits.
- Push your bug fixes and create a pull request against the hotfix branch: https://github.com/mozilla/glean/compare/hotfix-v25.0.1...your-name:bugfix?expand=1
- When that pull request lands, wait for CI to finish on that branch and ensure it's green:
- https://circleci.com/gh/mozilla/glean/tree/hotfix-v25.0.1
- You can find the TaskCluster task on the corresponding commit. See How to find TaskCluster tasks for details.
Finish a hotfix branch
When CI has finished and is green for your hotfix branch, you are ready to cut a release, similar to a normal release:
- Check out the main release branch:
git checkout release
- Merge the hotfix branch:
git merge --no-ff hotfix-v25.0.1
- Push the main release branch:
git push upstream release
- Tag the release on GitHub:
- Draft a New Release in the GitHub UI (
Releases > Draft a New Release
). - Enter
v<myversion>
as the tag. It's important this is the same as the version you specified to theprepare_release.sh
script, with thev
prefix added. - Select the
release
branch as the target. - Under the description, paste the contents of the release notes from
CHANGELOG.md
.
- Draft a New Release in the GitHub UI (
- Wait for the CI build to complete for the tag.
- You can check on CircleCI for the running build.
- You can find the TaskCluster task on the corresponding commit. See How to find TaskCluster tasks for details.
- Send a pull request to merge back the hotfix branch to the development branch: https://github.com/mozilla/glean/compare/main...hotfix-v25.0.1?expand=1
- This is important so that no changes are lost.
- This might have merge conflicts with the
main
branch, which you need to fix before it is merged.
- Once the above pull request lands, delete the hotfix branch.
- Update
glean-ffi
in the iOS megazord. See the application-services documentation for that.
Hotfix release for previous version
If you need to release a hotfix for a previously released version (that is: not the latest released version), you need a support branch.
Note: This should rarely happen. We generally support only the latest released version of Glean.
Create a support and hotfix branch
- Create a support branch from the version tag and push it:
git checkout -b support/v24.0 v24.0.0 git push upstream support/v24.0
- Create a hotfix branch for this support branch:
git checkout -b hotfix-v24.0.1 support/v24.0
- Fix the bug and commit the fix in one or more separate commits into your hotfix branch.
- Push your bug fixes and create a pull request against the support branch: https://github.com/mozilla/glean/compare/support/v24.0...your-name:hotfix-v24.0.1?expand=1
- When that pull request lands, wait for CI to finish on that branch and ensure it's green:
- https://circleci.com/gh/mozilla/glean/tree/support/v24.0
- You can find the TaskCluster task on the corresponding commit. See How to find TaskCluster tasks for details.
Finish a support branch
- Check out the support branch:
git checkout support/v24.0
- Update the changelog .
- Add any missing important changes under the
Unreleased changes
headline. - Commit any changes to the changelog file due to the previous step.
- Add any missing important changes under the
- Run
bin/prepare-release.sh <new version>
to bump the version number.- The new version should be the next patch version of the support branch.
- Let it create a commit for you.
- Push the support branch:
git push upstream support/v24.0
- Tag the release on GitHub:
- Draft a New Release in the GitHub UI (
Releases > Draft a New Release
). - Enter
v<myversion>
as the tag. It's important this is the same as the version you specified to theprepare_release.sh
script, with thev
prefix added. - Select the support branch (e.g.
support/v24.0
) as the target. - Under the description, paste the contents of the release notes from
CHANGELOG.md
.
- Draft a New Release in the GitHub UI (
- Wait for the CI build to complete for the tag.
- You can check on CircleCI for the running build.
- You can find the TaskCluster task on the corresponding commit. See How to find TaskCluster tasks for details.
- Send a pull request to merge back any bug fixes to the development branch: https://github.com/mozilla/glean/compare/main...support/v24.0?expand=1
- This is important so that no changes are lost.
- This might have merge conflicts with the
main
branch, which you need to fix before it is merged.
- Once the above pull request lands, delete the support branch.
Upgrading android-components to a new version of Glean
On Android, Mozilla products consume the Glean SDK through its wrapper in android-components
.
Therefore, when a new Glean SDK release is made, android-components
must also be updated.
After following one of the above instructions to make a Glean SDK release:
-
Ensure that CI has completed and the artifacts are published on Mozilla's Maven repository.
-
Create a pull request against
android-components
to update the Glean version with the following changes:-
The Glean version is updated in the
mozilla_glean
variable in thebuildSrc/src/main/java/Dependencies.kt
file. -
The relevant parts of the Glean changelog copied into the top part of the
android-components
changelog. This involves copying the Android-specific changes and the general changes to Glean, but can omit other platform-specific changes.
-
IMPORTANT: Until the Glean Gradle plugin work is complete, all downstream consumers of android-components will also need to update their version of Glean to match the version used in android-components so that their unit tests can run correctly.
In Fenix, for example, the Glean version is specified here.