From ca6b05f0864188e62612167d3f291e446d06c098 Mon Sep 17 00:00:00 2001 From: pelesh Date: Thu, 1 Oct 2026 13:13:45 -0400 Subject: [PATCH 1/4] Update documentation on release branch management. --- CONTRIBUTING.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8aa1a5de37..c464272759 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -98,6 +98,64 @@ Once your branch has been merged or is otherwise no longer needed, delete it from the GridKit™ GitHub repository. We recommend cleaning up soon after the merge and periodically going through your existing branches to cleanup. +### Creating a release branch + +Release branches are created by maintainers from `develop` once it contains +all features planned for the release. Name the branch `release-`. +``` +git checkout -b release-0.2 develop +``` +On the release branch, update the version number and +[CHANGELOG.md](CHANGELOG.md), and commit the changes. Only bug fixes and +release preparation are allowed on the release branch; new features go to +`develop`. Creating the release branch frees `develop` for the next +release's features. + +### Merging a release branch + +A release branch is merged twice: first into `main` and then back into +`develop`. Both merges are done through GitHub pull requests and must be +merged with a merge commit, not squashed or rebased, so that `main` and +`develop` share the release branch commits as common ancestors. +Alternatively, merge the branches on the command line with +``` +git checkout +git pull +git merge --no-ff release-0.2 +git push origin +``` +where `` is `main` or `develop`. + +Release branches are not deleted after the merges. A bug found after the +release is fixed on the release branch, the patch version is bumped (e.g., +`v0.2.1`), and the release branch is merged again into `main` and `develop` +following the same steps. + +#### Merging into `main` + +When the release branch is ready, create a pull request targeting `main`. +After the pull request is merged, tag the merge commit with the release +version and push the tag. +``` +git checkout main +git pull +git tag -a v0.2 -m "GridKit v0.2" +git push origin v0.2 +``` + +#### Merging into `develop` + +Create a pull request from the release branch targeting `develop`, so that +bug fixes made on the release branch are not lost. Resolve any merge +conflicts with features added to `develop` since the release branch was +created. + +If a fix applies only to the release and not to `develop`, still merge the +release branch, but resolve the conflict in favor of `develop` or revert the +fix on `develop` right after the merge, noting the reason in the commit +message. Do not cherry-pick individual fixes instead of merging, as this +loses the shared history between `main` and `develop`. + ## Documenting Code ### Doxygen From 5f12fc1a5638f2e7da110b7132a5a10ca592c83f Mon Sep 17 00:00:00 2001 From: pelesh Date: Thu, 1 Oct 2026 15:23:13 -0400 Subject: [PATCH 2/4] [skip ci] Apply suggestion from @nkoukpaizan Co-authored-by: Nicholson Koukpaizan <72402802+nkoukpaizan@users.noreply.github.com> --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c464272759..67bb07490c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -98,7 +98,7 @@ Once your branch has been merged or is otherwise no longer needed, delete it from the GridKit™ GitHub repository. We recommend cleaning up soon after the merge and periodically going through your existing branches to cleanup. -### Creating a release branch +### Creating a release branch (maintainers only) Release branches are created by maintainers from `develop` once it contains all features planned for the release. Name the branch `release-`. From a12a2036a63d7eebbcad503ef903b528894b65c5 Mon Sep 17 00:00:00 2001 From: pelesh Date: Thu, 1 Oct 2026 15:23:53 -0400 Subject: [PATCH 3/4] [skip ci] Apply suggestion from @nkoukpaizan Co-authored-by: Nicholson Koukpaizan <72402802+nkoukpaizan@users.noreply.github.com> --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 67bb07490c..00310cfd9f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -126,7 +126,7 @@ git push origin ``` where `` is `main` or `develop`. -Release branches are not deleted after the merges. A bug found after the +Unlike feature branches, release branches are not deleted after the merges. A bug found after the release is fixed on the release branch, the patch version is bumped (e.g., `v0.2.1`), and the release branch is merged again into `main` and `develop` following the same steps. From b9a2192b4dfe56444fe93d38fd98d88f03b3babf Mon Sep 17 00:00:00 2001 From: pelesh Date: Thu, 1 Oct 2026 15:24:19 -0400 Subject: [PATCH 4/4] [skip ci] Apply suggestion from @nkoukpaizan Co-authored-by: Nicholson Koukpaizan <72402802+nkoukpaizan@users.noreply.github.com> --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 00310cfd9f..d742f6ff06 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -111,7 +111,7 @@ release preparation are allowed on the release branch; new features go to `develop`. Creating the release branch frees `develop` for the next release's features. -### Merging a release branch +### Merging a release branch (maintainers only) A release branch is merged twice: first into `main` and then back into `develop`. Both merges are done through GitHub pull requests and must be