Release Procedures

This document outlines the few manual steps that Kargo maintainers must follow to orchestrate a minor or major release of Kargo.

Conventions

Throughout this document, we will use:

• M and m to denote the major and minor version numbers of the upcoming release (i.e. the one being performed), respectively.

• M-1 and m-1 to denote the previous major and minor version numbers, respectively.

• M+1 and m+1 to denote the next major and minor version numbers, respectively.

• L to denote the latest minor version of the M-1 line.

Timeline

The steps outlined below should be started on the Monday preceding the expected release date -- which is always a Friday.

Steps

1. Open a PR similar to this one to revise the roadmap.

   • The roadmap should be updated to reflect that work for the vM.m.0 release is complete.

   • Planned work that was not completed should be moved to a future release.

   • The next release (vM.m+1.0 or vM+1.0.0) should be updated to reflect that work is in-progress, along with the expected release date.

     note

     "Edge" documentation at main.kargo.akuity.io is continuously published from the main branch and production documentation at kargo.akuity.io is continuously published from the previous release branch (release-M.m-1 or release-M-1.L). There are two consequences of this:

     • The production documentation will not immediately reflect changes made to the main branch, nor will it reflect changes made to the release branch for the upcoming release. (Which does not exist yet. See next step.)

     • This step should ideally be performed prior to the creation of the release branch (see next step) in order to avoid the need for two separate PRs to update both branches.

2. Create a release branch of the form release-M.m.

   This can be done locally by a maintainer. Presuming upstream is a remote pointing to the main Kargo repository:

   git checkout main
   git pull upstream main
   git checkout -b release-M.m
   git push upstream release-M.m
   note

   After the creation of this branch, anything merged to main is excluded from the upcoming release unless explicitly cherry-picked into the release-M.m branch. As such, this step should ideally be performed after the majority of work for the upcoming release is complete.

   In some cases, this may be performed early to:

   • Un-block work on the next release.
   • Facilitate the creation of a release candidate for use by non-engineers while work on the upcoming release continues.

3. Merge any release-specific upgrade logic into the release-M.m branch.

   info

   Pre-v1.0.0, we are making a best effort to automatically compensate for breaking changes between minor releases for users upgrading directly from any release in the v0.m-1 line. This means release-specific upgrade logic does not need to be merged into main.

4. Open a PR similar to this one against the previous release branch (release-M.m-1 or release-M-1.L) to lock production documentation (e.g. for download and installation procedures) into permanently reflecting the latest stable release.

   note

   Production documentation is continuously published from the previous release branch, so this step is necessary to ensure that the production documentation is not inadvertently broken by any subsequent steps.

   This step will also ensure that when the current production documentation is archived, it will reflect the latest release to which that documentation was applicable.

5. Cut vM.m.0-rc.1 from the Kargo release page.

   • The release process itself is fully-automated.
   • Be certain to reference the head of the release-M.m branch and not main.
   • Be sure to check the "Set as a pre-release" box.
   • Wait for the automated release process to complete.

6. Open a PR like this one against main to make the edge documentation (e.g. for download and installation procedures) reflect the recently built release candidate.

   info

   The edge documentation is continuously published from the main branch, so this step makes it easy for non-engineers to test the release candidate by adhering to instructions in the edge documentation, without any need to compensate for the release candidate not being counted as "latest" on account of being a pre-release.

7. Alert non-engineer stakeholders to the availability of the release candidate.

8. Bug fixes and last minute features should be merged to main and backported to the release-M.m (in bulk, when possible).

9. Repeat steps 5-8 as necessary until the release candidate is deemed stable by relevant stakeholders.

10. Draft release notes for the upcoming release.

    info

    This can be done concurrently with the previous steps.

    Some stakeholders may desire early access to these notes to inform blog posts, marketing materials, etc.

11. Cut vM.m.0 from the Kargo release page.

    • Be certain to reference the head of the release-M.m branch and not main.
    • Be certain to include the final draft of the release notes.
    • Be sure to check the "Set as the latest release" box.
    • Wait for the automated release process to complete.

12. Mark the release branch (release-M.m) as the "Production branch" in Netlify.

    • Also add the previous release branch (release-M.m-1 or release-M-1.L) to "Branch deploys".
    • After changing the "Production branch", it will be necessary to manually trigger a deployment of the production documentation.

13. Open a PR to revert the changes from step 6.

14. Inform relevant stakeholders that the release is complete.

15. 🎉 Celebrate!