Skip to content

contributing: Update release howto after the 8.4.2 release #6765

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
wenzeslaus wants to merge 3 commits into
base: main
Choose a base branch
from
Open

contributing: Update release howto after the 8.4.2 release #6765

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
149afbb
contributing: Update release howto after the 8.4.2 release
wenzeslaus Dec 19, 2025
a3b7867
Merge branch 'main' into update-release-howto-after-8.4.2
echoix Dec 23, 2025
5245a19
Merge branch 'main' into update-release-howto-after-8.4.2
echoix Dec 23, 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
113 changes: 49 additions & 64 deletions doc/howto_release.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ _Note: Some later steps in this text are to be done by the development coordinat
Update your remotes and switch to branch:

```bash
git fetch --prune upstream && git checkout releasebranch_8_4
git fetch --prune upstream && git switch releasebranch_8_4
```

Confirm that you are on the right branch and have no local changes
Expand Down Expand Up @@ -82,16 +82,27 @@ For a release, change the version after the RC cycle to an official release:
The script will compute the correct version string and print a message
containing it into the terminal (e.g., "version: GRASS 3.5.0RC1").

## Create variables

For convenience, create Bash variables with the version update script:

```bash
# Get VERSION and TAG as variables.
eval $(./utils/update_version.py status --bash)
```

If in doubt, run the script without `eval $(...)` to see all the variables created.

## Return to the work

Commit with a commit message suggested by the script, e.g.:

```bash
git diff
./utils/update_version.py suggest
git commit include/VERSION -m "..."
```

If you lost the script output with the suggested message use
`./utils/update_version.py suggest` to get it.

Check that there is exactly one commit on your local branch and that it is the
version change:

Expand All @@ -106,24 +117,6 @@ Push the commit to the upstream repo:
git push upstream
```

## Create variables

For convenience, create Bash variables with the version update script:

```bash
# Get VERSION and TAG as variables.
eval $(./utils/update_version.py status --bash)
```

Version and tag are the same for all releases:

```bash
echo "$VERSION"
echo "$TAG"
```

If in doubt, run the script without `eval $(...)` to see all the variables created.

## Create release tag

The tag is created locally, while the release draft is created automatically by
Expand All @@ -134,11 +127,7 @@ see: <https://help.github.com/en/articles/creating-releases>.

Before creating the tag, it is a good idea to see if the CI jobs are not failing.
Check on [GitHub Actions](https://github.com/OSGeo/grass/actions)
or use GitHub CLI:

```bash
gh run list --branch releasebranch_8_4
```
or [GitHub Branches](https://github.com/OSGeo/grass/branches).

Some time was needed to run the checks, so before getting back to creating the tag,
confirm that you are on the right branch which is up to date:
Expand Down Expand Up @@ -186,17 +175,22 @@ good results for the first release candidate because it contains contributor han
and can identify new contributors, so use with the _api_ backend, e.g.:

```bash
python ./utils/generate_release_notes.py api releasebranch_8_4 8.3.0 $VERSION
python ./utils/generate_release_notes.py api $(git rev-parse --abbrev-ref HEAD) 8.3.0 $VERSION
Copy link
Member

@echoix echoix Dec 19, 2025

Choose a reason for hiding this comment

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

We have to remember that it is probably not always relative to 8.3.0. The previous line made it clear to me when reading, the new line not as much


```

Note that new contributors are the unknown authors, so update the authors,
but also manually create a new contributors section from the original
output of the script.

#### Micro releases

For micro releases (x.y.Z), GitHub API does not give good results because it uses
PRs while the backports are usually direct commits without PRs.
PRs while the backports are usually direct commits without PRs (cherry-picks).
The _git log_ command operates on commits, so use use the _log_ backend:

```bash
python ./utils/generate_release_notes.py log releasebranch_8_4 8.4.0 $VERSION
python ./utils/generate_release_notes.py log $(git rev-parse --abbrev-ref HEAD) 8.4.1 $VERSION
```

#### Between RCs and from last RC to final release
Expand All @@ -205,10 +199,10 @@ In between RCs and between last RC and final release, the _log_ backend is usefu
for showing updates since the last RC:

```bash
python ./utils/generate_release_notes.py log releasebranch_8_4 8.4.0RC1 $VERSION
python ./utils/generate_release_notes.py log $(git rev-parse --abbrev-ref HEAD) 8.4.0RC1 $VERSION
```

#### Finalizing the release notes
#### Edit the release notes

For the final release, the changes accumulated since the first RC need to be
added manually to the result from the _api_ backend.
Expand All @@ -218,7 +212,8 @@ However, these notes need to be manually edited to collapse related items into
one. Additionally, a _Highlights_ section needs to be added on top with manually
identified new major features for major and minor releases. For all releases, a
_Major_ section may need to be added showing critical fixes or breaking changes
if there are any.
if there are any. Similarly, an _Errata_ section should be added when
numerical results changed due to a fix of an computational issue.

### Modify the release draft

Expand Down Expand Up @@ -260,30 +255,35 @@ Use `--help` for details about the options.
Eventually, commit with the suggested commit message and push, e.g.:

```bash
git show
git diff
eval $(./utils/update_version.py status --bash)
git commit include/VERSION -m "version: Back to $VERSION"
./utils/update_version.py suggest
git commit include/VERSION -m "..."
git show
git push upstream
```

The message was suggested by the script, but if you lost that output,
you can get the same or similar message again using the script
(the message provided this way is not precise after RCs):
A precise message was suggested by the script when switching the version,
but if you lost that output, the _suggest_ subcommand can get the same or,
similar message again, although the message provided this way is not
precise after RCs (the script lacks the context about the change unless
it is doing it).

```bash
./utils/update_version.py suggest
```

## Publishing a final release
## Publish the release on GitHub

The published RC releases has the initial release notes (based on locally
auto-generated notes) which need to be refined further:
To finish the GitHub-part of the release, find the draft at
<https://github.com/OSGeo/grass/releases>.
Edit the draft of the release again,
reviewing the section about editing the release notes above.
To publish it, use the "Publish release" button.

- add highlights
- verify that the subsections are well sorted
## Close milestone

For the final release, edit these draft release again in order to publish it
using the "Publish release" button.
For a final release (not release candidate), close the related milestone at
<https://github.com/OSGeo/grass/milestones>.
If there are any open issues or PRs, move them to another milestone
in the milestone view (all can be moved at once by selecting the open
issues and PRs and reassigning the next milestone).

## Upload to OSGeo servers

Expand Down Expand Up @@ -416,21 +416,6 @@ Add the new version to repos which build or test addons:
- <https://github.com/landam/wingrass-maintenance-scripts/blob/master/grass_addons.sh>
(add new release related line for new branches and final releases)

## Close milestone

For a final release (not release candidate), close the related milestone at
<https://github.com/OSGeo/grass/milestones>.
If there are any open issues or PRs, move them to another milestone
in the milestone view (all can be moved at once by selecting the open
issues and PRs and reassigning the next milestone).

## Publish the release

When the above is done and the release notes are ready, publish the release at
<https://github.com/OSGeo/grass/releases>.

Release is done.

## Improve release description

For final releases only, go to [Zenodo](https://doi.org/10.5281/zenodo.5176030)
Expand Down
Loading