Skip to content

25.12 updated Maintainer Docs - Git Methodology #721

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
rockhowse wants to merge 2 commits into
base: main
Choose a base branch
from
Open

25.12 updated Maintainer Docs - Git Methodology #721

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2accba0
25.12 updated Maintainer Docs - Git Methodology
rockhowse Dec 12, 2025
7f789cf
spelling
rockhowse Dec 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 12 additions & 16 deletions resources/git.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,37 +24,33 @@ Developers

* [Versioning and Tagging]({% link resources/versions.md %})
* [Hotfix releases]({% link releases/hotfix.md %})
* [Major and minor releases]({% link releases/process.md %})
* [Releases]({% link releases/process.md %})

## Git branching

### Approach

Our development approach involves protecting the `main` branch so that it becomes the official release record for any RAPIDS project. Development PRs will be merged into a release branch, which will be merged into main and tagged only when the release is ready. The only other merges to `main` are hotfixes.
Our development approach involves using the `main` branch as the main development branch. When a release occurs it will use the [Versioning and Tagging]({% link resources/versions.md %}) and [Release]({% link releases/process.md %}) procedures.

### Development workflow

All PRs are merged into a release branch named `branch-M.B` where `M` is the major version and `B` is the minor version number. Release branches are created from the previous release branch when the decision has been made to **freeze** the release.
All PRs are merged into `main`. Release branches are created from `main` when the decision has been made to start the the **burndown** process for the release.

To **freeze** a release branch is to stop new development for the release, and focus on completing outstanding features and any bugs discovered from testing. Once this **freeze** happens a new branch `branch-M.C` (where `C=B+1`) is created so development can continue. Updates to `branch-M.B` can be merged as needed to `branch-M.C`, but generally will wait until the release is finished. This means that `branch-M.X` (where `X` is the highest minor version) the latest and greatest code.
To **burndown** a release branch is to stop new development for the release, and focus on completing outstanding features and any bugs discovered from testing. Once this **burndown** happens, the dependencies in the `main` branch are updated to `YY.MB` so development can continue on any features not going into `YY.MA`. Updates to `release/YY.MA` will be [forward-merged]({% link resources/auto-merger.md %}) into `main`, and any merge conflicts are handled as part of this forward merge process. This means any fixes found during ***burndown*** make it to `main`, which contains the latest and greatest code.
Copy link
Contributor

@AyodeAwe AyodeAwe Dec 16, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Burndown is the process of completing all issues scheduled for the upcoming release and moving other outstanding issues to the next release.

We actually don't stop development at this point. We do that at freeze


Hotfixes (patch releases) related to the current release `M.A` are directly merged to `main` from a PR and then those changes are also merged to the current release branches in progress through an automated process. All merges to `main` trigger an automated CI job that will produce a new release and tag incrementing the patch version off of the previous highest tag in the repo. Once the tag is set, the automated CI build for conda packages creates and pushes new packages for users. This includes the version change enabling known good builds and the ability to rollback.
Hotfixes (patch releases) related to the current release `YY.MA` are directly merged to `main` from a PR and then those changes are also merged to the current release branches in progress through an automated process. All merges to `main` trigger an automated CI job that will produce a new release and tag incrementing the patch version off of the previous highest tag in the repo. Once the tag is set, the automated CI build for conda packages creates and pushes new packages for users. This includes the version change enabling known good builds and the ability to rollback.
Copy link
Contributor

@AyodeAwe AyodeAwe Dec 16, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I described the hotfix process in this other comment:

#716 (comment)

Copy link
Contributor Author

@rockhowse rockhowse Dec 16, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yup will update accordingly, thx for flagging this.


Minor (and eventually, Major) release development takes place on the current release branch. PRs can be edited on GitHub to set the target base branch for merging the PR. It is the reviewer's responsibility to ensure the PR is targeted for the correct and planned release branch. Once PRs have passed all tests, they are merged to their release branch, which triggers an automated CI build for conda packages that will be marked as development, such as M.N-dev1. These can be inspected by the team to ensure the build works as intended and perform larger testing.
PRs can be edited on GitHub to set the target base branch for merging the PR. It is the reviewer's responsibility to ensure the PR is targeted for the correct and planned release branch. Once PRs have passed all tests, they are merged to their release branch, which triggers an automated CI build for conda packages that will be marked as development and pushed to the [rapidsai-nightly](https://anaconda.org/rapidsai-nightly/) channel hosted on anaconda. These can be inspected by the team to ensure the build works as intended and perform larger testing.

Once a release has been reviewed and signoff has been given, a PR is created to merge the release branch to main. After the merge, the automated tagging process tags and releases a minor version and kicks off the conda builds for the public release.
Once a release has been reviewed and signoff has been given, the automated tagging process tags and kicks off the conda builds for the public release.

### Summary

- The `main` branch is the official release history (including hotfixes).
- The tip of `main` is intended to be always working given the testing and reviews of merged PRs.
- Hotfixes (patch releases) are automatically tagged for every push to `main`.
- Release branches are used for development of the next releases and **all PRs except for hotfixes** are merged to the current release branch.
- A new release branch is created from the previous release branch after the release **freeze** (see above).
- After the **freeze** and before the release branch is merged, there are two release branches; however, active development should take place in the next release branch, while cleanup and finalization happens in the frozen branch.
- This gives the highest numbered `branch-M.X` (modulo hot fixes and unmerged frozen release fixes) the latest and greatest code.
- Minor releases are done by creating a PR for the minor release from the associated release branch.
- After review and sign off by the team, the PR is merged into main.
- Development stays on `main` branch (not moving to `release/YY.MX`)
- Releases happen on `release/YY.MX` branches (not on `main`)
- Forward merger automatically merges changes from release branches to main
- Alpha tags distinguish development versions (e.g., `v26.02.00a`) from release versions (e.g., `v25.12.00`)
- `RAPIDS_BRANCH` file replaces alpha suffixes for dependency resolution

## Large files and git

Expand Down