Release Process

(Work In Progress)

Release Timeline and Schedule

Kokkos follows a time-based release schedule to provide predictable updates to the community:

  • Major releases (X.0.0): Every 3 years

  • Minor releases (X.Y.0): Every 4 months

  • Patch releases (X.Y.Z): As needed for bug fixes

Annual Release Cadence

Kokkos follows a three-cycle annual schedule with releases in March, July, and November:

Release Calendar

Month

Activity

Notes

February

Branch Creation

Last week: Create release-candidate-X.Y.0 branch

March

X.Y.0 Release

Mid-to-late March (3 weeks after branch creation)

April

Patch Release

X.Y.1 released if needed (~6 weeks after branch creation)

May

Patch Releases

X.Y.2+ released as needed

June

Branch Creation

Last week: Create next release candidate branch

July

X.Y.0 Release

Mid-to-late July

August

Patch Release

X.Y.1 released if needed

September

Patch Releases

X.Y.2+ released as needed

October

Branch Creation

Last week: Create next release candidate branch

November

X.Y.0 Release

Mid-to-late November

December

Patch Release

X.Y.1 released if needed

Release Cycle Timeline

Each minor release follows a structured timeline:

Week  0: Release branch created (last week of Feb/Jun/Oct)
         - Feature freeze for this release
         - Develop branch version bumped to X.Y.99

Week  1-3: Testing and stabilization phase
           - Cherry-pick critical fixes
           - Run extended CI and integration tests
           - Update changelog and documentation

Week  3: X.Y.0 Released (mid-to-late Mar/Jul/Nov)
         - Create Git tag
         - Publish GitHub release
         - Announce to community

Week  5: Release briefing

Week  6: X.Y.1 Released (as needed)
         - First patch release with accumulated bug fixes

Week  6-17: X.Y.2+ Released (as needed)
            - Additional patches for critical issues

Week 17: Next release branch created
         - Cycle repeats (approximately 4 months or 17 weeks)

Release Phase Guidelines

Weeks 0-1 (Early Release Candidate):

  • Cherry-pick bug fixes, and feature completions

  • Broad testing across supported platforms

  • Documentation updates

Weeks 2-3 (Late Release Candidate):

  • Increasingly conservative - focus on critical bugs and regressions only

  • Final documentation review

  • Changelog finalization

Week 3 onwards (Post-Release):

  • Patch releases follow stricter criteria (bug fixes only)

  • Maintain API compatibility with X.Y.0

Note

The release schedule may be adjusted for holidays, critical bugs, or coordination with major downstream projects.

Create Release Branch and Update Project Version

(For maintainers)

Note

Version Numbering Scheme

Development versions use .99 as the patch number to ensure they always compare as more recent than any release in that series (e.g., 4.2.99 > 4.2.5). This allows code to reliably discriminate between development and release versions.

Feature Releases (X.Y.0)

Important

Steps 1-7 must be completed in sequence without merging other changes to develop. This ensures accurate version tracking throughout the codebase.

  1. Check that the develop branch is in decent shape with the Continuous Integration Working Group, that all nightly builds are passing, and that there are no outstanding issues in the integration testing.

  2. Create the release candidate branch:

git checkout -b release-candidate-X.Y.0

  1. Update the version number to X.Y.0 in the root CMakeLists.txt:

# Edit these lines in CMakeLists.txt:
set(Kokkos_VERSION_MAJOR X)
set(Kokkos_VERSION_MINOR Y)
set(Kokkos_VERSION_PATCH 0)

Then commit the change:

git commit -s -m 'Set version number to X.Y.0' CMakeLists.txt

  1. Push the release candidate branch to the upstream repository:

git push https://github.com/kokkos/kokkos.git release-candidate-X.Y.0

  1. Create and checkout a new bump_version_number branch with develop as the starting point:

git checkout -b bump_version_number develop

  1. Update the version from X.(Y-1).99 to X.Y.99 in the root CMakeLists.txt:

# Edit these lines in CMakeLists.txt:
set(Kokkos_VERSION_MAJOR X)
set(Kokkos_VERSION_MINOR Y)
set(Kokkos_VERSION_PATCH 99)

Then commit the change:

git commit -s -m 'Bump version from X.(Y-1).99 to X.Y.99' CMakeLists.txt

  1. Push to your fork and open a pull request against the develop branch:

git push <your-fork-remote> bump_version_number

This pull request must be merged immediately before any other feature PRs to maintain version integrity in the development branch.

  1. Open a tracker issue for the X.(Y+1) changelog and pin it to the repository (use GitHub’s “Pin issue” feature). Unpin the old X.Y changelog issue. Use the old issue as a template, keeping all sections but clearing the entries.

  2. Notify developers on the #nucleus channel that the release branch has been created and that the version bump PR needs to be merged as the next change to develop.

Patch Releases (X.Y.Z)

Patch releases are created from the previous release tag to incorporate critical bug fixes into an existing release series.

Note

Unlike feature releases, patch releases do not require updating the develop branch version, as it already uses the .99 patch number for the current development series.

  1. Create the release candidate branch from the latest patch release tag:

git checkout -b release-candidate-X.Y.(Z+1) X.Y.Z

  1. Update the version number from X.Y.Z to X.Y.(Z+1) in the root CMakeLists.txt:

# Edit these lines in CMakeLists.txt:
set(Kokkos_VERSION_MAJOR X)
set(Kokkos_VERSION_MINOR Y)
set(Kokkos_VERSION_PATCH Z+1)

Then commit the change:

git commit -s -m 'Bump version from X.Y.Z to X.Y.(Z+1)' CMakeLists.txt

  1. Push the release candidate branch to the upstream repository:

git push https://github.com/kokkos/kokkos.git release-candidate-X.Y.(Z+1)

  1. Proceed to cherry-picking approved changes (see next section).

Cherry-Picking Changes into Release Candidates

General Workflow

Changes should follow the develop-first workflow unless there is an exceptional reason, such as:

  • Develop has diverged significantly, making cherry-picking impractical

  • Develop is temporarily broken or in an untestable state

  • The bug only exists in the release branch due to subsequent fixes in develop

  • Develop contains incompatible changes requiring a fundamentally different fix

  1. Merge to develop first: All changes must be integrated and tested on the develop branch before being considered for backporting.

  2. Get authorization: Once merged to develop, obtain approval from a maintainer, through the weekly developer meeting, or on the #nucleus channel before backporting.

  3. Open cherry-pick PR: Create a pull request targeting the release candidate branch with:

    • Title format: [X.Y.Z] Original Well-Crafted Subject Line

    • Description starts with: “Cherry-picking the changes from PR #1234 into the X.Y.(Z+1) release candidate branch”

Tip

Developers are encouraged (but not required) to seek approval before opening the backport PR to avoid unnecessary work if the change is deemed inappropriate for the release.

Scope Guidelines for Feature Release Candidates (X.Y.0)

During the release candidate phase for a new feature release, patches should be limited to:

  • Bug fixes discovered during testing

  • Important optimization improvements that significantly impact performance

  • Completion of features that were started before the branch was created

Warning

As the release date approaches, patches should be increasingly conservative and limited to:

  • Critical bugs that affect core functionality

  • Regressions from the previous release

  • Build system failures on supported platforms

Scope Guidelines for Patch Releases (X.Y.Z, Z > 0)

Patches for bug fix releases have stricter requirements:

  • Bug fixes only (preferred)

  • Very safe and critical performance improvements (requires strong justification)

  • Must maintain full API compatibility with the X.Y.0 release

Important

Patch releases exist to provide stability for users who have already deployed the X.Y.0 release. Breaking changes of any kind are not acceptable.

Final Tasks

(For maintainers)

Automated Steps

  1. Tag and push the release:

git tag --sign X.Y.Z
git push https://github.com/kokkos/kokkos.git X.Y.Z

The release workflow will automatically generate downloadable source code archives (.zip and .tar.gz) for the X.Y.Z Git tag, it will compute the corresponding SHA-256 checksums, create a kokkos-X.Y.Z-SHA-256.txt file, and upload them to the release page. It will draft release notes with tables gathering links to the source distributions and summary files.

Manual Verification Steps

  1. Verify checksums:

Once the GitHub CI Action has run, download and verify the integrity of the generated artifacts:

sha256sum -c kokkos-X.Y.Z-SHA-256.txt

  1. Sign the checksum file:

gpg --detach-sig --armor kokkos-X.Y.Z-SHA-256.txt

Publish the Release

4. Navigate to the release page on GitHub (https://github.com/kokkos/kokkos/releases/latest):

  • Click the “Edit” button

  • Adjust the release date to YYYY-MM-DD

  • In the release notes, add your GPG signing key information (e.g., Digitally signed with [Key short ID](link-to-public-key))

  • Upload the kokkos-X.Y.Z-SHA-256.txt.asc signature file

  • Click “Update release”

Double-check that everything looks good. Congratulations, the release is shipped!

Note

The CI/CD Action publishes the X.Y.Z release as the “Latest” release on GitHub. If this is a patch release for an older version (e.g., releasing 4.7.3 after 5.0.0 is already out), you may need to manually change which release is marked as “Latest”.