Skip to content

Latest commit

 

History

History
174 lines (119 loc) · 10.9 KB

meilisearch-release.md

File metadata and controls

174 lines (119 loc) · 10.9 KB
Raw

Meilisearch release process

This guide is to describe how to make releases and pre-releases for the Meilisearch repository.

At the beginning of the pre-release phase, the first RC is released. Other RCs will be done if bugs are found.

At the end of the pre-release phase, the official release is published.

📚 More information about the sprint organization and the different sprint phases in this guide.

🏋️‍♂️ Meilisearch pre-release phase

How to create the first pre-release (or RC i.e. Release Candidate)

In the Meilisearch repository:

  1. Ensure:
  • the version of Meilisearch in the Cargo.toml files on the main branch has been updated. Use our automation if not -> click on Run workflow, and fill the appropriate version before validating. A PR updating all the versions in the Cargo.toml files will be created.
  • A GitHub Milestone has been opened for this new version.
  1. Make sure you are on the main branch and pull the last commits:
git checkout main
git pull origin main
  1. Create a release branch named release-vX.Y.Z where X.Y.Z is the new version and push this branch
git checkout -b release-vX.Y.Z
git push -u origin release-vX.Y.Z
  1. Copy/paste this TODO steps on your side
RC todo - [ ] Launch RC on the GitHub interface
- [ ] Adapt changelog in the related PR: make a commit suggestion, or, if too big, open a PR.
- [ ] Check binaries and Docker images are ready: check the assets are attached to the release + run the Docker image on your machine to ensure it starts correctly (at least)
- [ ] Manually run SDK tests with the new RC, and ensure the failing tests are expected
- [ ] Make a message on #ms-release to announce the new RC: highlight the new changes if impactful for other teams, and link the link of the release.

  1. Go to the GitHub interface, in the Release section.

  2. Click on the Draft a new release button

  3. Fill the form with:

  • the title of the release: vX.Y.Z-rc.0
  • the tag associated to the release: should be vX.Y.Z-rc.0
  • ⚠️ the branch on which to push the tag: release-vX.Y.Z. Do not push the tag to main!
  • the description:
    • if rc0: use the changelogs in the related PR.
      • ⚠️ Some lines of the changelogs must be removed; check the comments carefully
      • ⚠️ Remove any remaining TBD.
      • remove the title of the changelogs ("vX.Y.Z release changelogs").
      • And don't forget, anything that is not currently merged in meilisearch should not be part of the changelog (i.e., We merged something in charabia but didn’t update charabia in meilisearch => not mentioned in the changelog yet but will probably be in the next RC).
    • if not rc0: add as many details as possible (link the PRs, the authors of PR, the new usage, the external contributors we want to thank...)
  • ⚠️⚠️ the This is a pre-release check box

GH release form

  1. Finally, when you are sure, click on the Publish release button.

⚙️ The CIs will be triggered to:

  • upload binaries to the associated GitHub pre-release.
  • publish the associated Docker image (vX.Y.Z) to DockerHub.
  1. Ensure you made all steps in the TODO you copied/pasted at step 4.

What if some bugs are in the RC?

  1. Create a new branch starting from the branch release-vX.Y.Z and commit on this new branch.

  2. Open and merge the PR originating this new branch and pointing to release-vX.Y.Z

How to release the next RCs

When all/enough hotfixes have been done to the release-vX.Y.Z branch, create a new RC. The steps are the same as for How to create the first pre-release (or RC i.e. Release Candidate) but starting from step 4 and with the new RC name.

🔥 Meilisearch official release

How to do the official release

  1. Copy/paste this TODO steps on your side
Release todo - [ ] Launch the release on the GitHub interface
- [ ] Check binaries and Docker images are ready: check the assets are attached to the release + run the Docker image on your machine to ensure it starts correctly (at least)
- [ ] Check the Homebrew PR has been created.
- [ ] Once everything is deployed, make a message on #ms-release to announce the new release: if doing a non-patch release, ping the integration-team and docs-team since they should deploy their own scope now.
- [ ] Bring back commits on the release-vX.Y.Z branch into main branch (cf this section)

  1. Go to the GitHub interface, in the Release section.

  2. Click on the Draft a new release button

  3. Fill the form with:

  • The title of the release: vX.Y.Z
  • The tag associated to the release: should be vX.Y.Z
  • ⚠️ The branch on which to push the release: release-vX.Y.Z. Do not push the tag to main!
  • The description:
    • For non-patch release: use the changelogs in the related PR. ⚠️ Some lines of the changelogs must be removed; check the comments carefully and if there is any remaining TBD. Also, remove the title of the changelogs ("vX.Y.Z release changelogs").
    • For patch release: add as many details as possible (link the PRs, the authors of PR, the new usage, the external contributors we want to thank...)
  • Check the Set as the latest release (if it indeed should be considered as the latest)

GH release form

  1. Finally, when you are sure, click on the Publish release button.

⚙️ The CIs will be triggered to:

  1. Ensure you complete all the TODO tasks you copied/pasted at step 1.

After the release: bring back changes to main

Some commits might miss to main since the engine-team did some hotfixes merged to the release-vX.Y.Z branch.

In this case, you need to bring them back from release-vX.Y.Z to main by creating and merging a PR originating release-vX.Y.Z and pointing to main.

⚠️ If you encounter any git conflicts when creating the PR, please do NOT fix the git conflicts directly on the release-vX.Y.Z branch. It would bring the changes present in main into release-vX.Y.Z, which would break a potential future patched release.

GitHub interface showing merge conflicts

Instead:

  • Create a new branch originating release-vX.Y.Z, like tmp-release-vX.Y.Z
  • Create a PR from the tmp-release-vX.Y.Z branch and pointing to main
  • Fix the git conflicts on this new branch
    • By either fixing the git conflict via the GitHub interface
    • By pulling the main branch into temp-release-vX.Y.Z and fixing them on your machine.
  • Merge this new PR into main

How to do patched release (following hotfixes)

It happens some releases come with impactful bugs in production (e.g. indexation or search issues): we obviously don't wait for the next cycle to fix them and we release a patched version of Meilisearch.

  1. Create a new release branch starting from the latest stable Meilisearch release (latest git tag or release-vX.Y.Z branch).
# Ensure you get all the current tags of the repository
git fetch origin --tags --force

# Create the branch
git checkout release-vX.Y.Z # The latest release you want to patch
git checkout -b release-vX.Y.Z # Increase the Z here
git push -u origin release-vX.Y.Z

  1. Open a new GitHub Milestone vX.Y.Z related to this new version.

  2. Change the version in Cargo.toml file. You can use our automation -> click on Run workflow -> Fill the appropriate version and run it on the newly created branch release-vX.Y.Z -> Click on "Run workflow". A PR updating the version in the Cargo.toml and Cargo.lock files will be created.

  3. Open and merge the PRs (fixing your bugs): they should point to release-vX.Y.Z branch.

  4. Follow all the steps in the "How to do the official release" section with the patched version name.

  5. Same as the official release, if needed, bring the new commits back from release-vX.Y.Z to main (or in a release branch if in pre-release) by merging a PR originating release-vX.Y.Z and pointing to main. If you encounter any merge conflict please refer to this point.

⚠️ If doing a patch release that should NOT be the latest release:

  • Do NOT check Set as the latest release when creating the GitHub release. If you did, quickly interrupt all CIs and delete the GitHub release!
  • Once the release is created, you don't have to care about Homebrew, APT and Docker CIs: they will not consider this new release as the latest; the CIs are already adapted for this situation.
  • However, the CI updating the latest git tag is not working for this situation currently and will attach the latest git tag to the just-created release, which is something we don't want! If you don't succeed in stopping the CI on time, don't worry, you just have to re-run the old CI corresponding to the real latest release, and the latest git tag will be attached back to the right commit.

🎈 Other library release process

The release process of other repositories maintained by the engine team is described in the corresponding CONTRIBUTING.md of each repository.