From c53ea578d23583abfb674642249156331a3d6ad7 Mon Sep 17 00:00:00 2001 From: Markus Neteler Date: Tue, 3 Oct 2023 22:14:38 +0200 Subject: [PATCH] docs: update howto_release.md (G83) (#3197) - finetuning of instructions after last 8.3.0 release - markdown prettified with: `npx prettier --print-width 80 -w doc/howto_release.md` --- doc/howto_release.md | 114 +++++++++++++++++++++---------------------- 1 file changed, 56 insertions(+), 58 deletions(-) diff --git a/doc/howto_release.md b/doc/howto_release.md index 2c5cef7267e..3065398730b 100644 --- a/doc/howto_release.md +++ b/doc/howto_release.md @@ -11,8 +11,8 @@ - You don't have any local un-pushed or un-committed changes. - You are using Bash or a similar shell. -*Note: Some later steps in this text are to be done by the development coordinator -(currently Markus Neteler and Martin Landa) due to needed logins.* +_Note: Some later steps in this text are to be done by the development coordinator +(currently Markus Neteler and Martin Landa) due to needed logins._ ## Prepare the local repo @@ -63,13 +63,19 @@ git show ## Update VERSION file to release version number -Modify the VERSION file use the dedicated script, for RC1, e.g.: +For RCs, modify the VERSION file use the dedicated script. E.g., for RC1: ```bash ./utils/update_version.py status ./utils/update_version.py rc 1 ``` +For a release, change the version after the RC cycle to an official release: + +```bash +./utils/update_version.py release +``` + The script will compute the correct version string and print a message containing it into the terminal (e.g., "version: GRASS GIS 3.5.0RC1"). @@ -80,9 +86,6 @@ git diff 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: @@ -91,7 +94,7 @@ git status git show ``` -Push the tag to the upstream repo: +Push the commit to the upstream repo: ```bash git push upstream @@ -139,7 +142,8 @@ git log --max-count=5 ``` Create an annotated tag (a lightweight tag is okay too, but there is more metadata -stored for annotated tags including a date; message is suggested by the version script): +stored for annotated tags including a date; message is suggested by the +`./utils/update_version.py` script): ```bash git tag $TAG -a -m "..." @@ -152,7 +156,8 @@ git tag -n --sort=-creatordate git tag -n --sort=-taggerdate ``` -Now push the tag upstream - this will trigger the automated workflows linked to tags: +Now push the tag upstream - this will trigger the +[automated workflows](https://github.com/OSGeo/grass/actions) linked to tags: ```bash git push upstream $TAG @@ -165,13 +170,13 @@ so that you can continue in the release process. Generate a draft of release notes using a script. The script the script needs to run from the top directory and will expect its configuration files -to be in the *utils* directory. +to be in the _utils_ directory. #### Major and minor releases -For major and minor releases, GitHub API gives good results for the first -release candidate because it contains contributor handles and can identify -new contributors, so use with the *api* backend, e.g.: +For major (X.y.z) and minor (x.Y.z) releases, GitHub API gives good results for the +first release candidate because it contains contributor handles and can identify +new contributors, so use with the _api_ backend, e.g.: ```bash python ./utils/generate_release_notes.py api releasebranch_8_3 8.2.0 $VERSION @@ -179,9 +184,9 @@ python ./utils/generate_release_notes.py api releasebranch_8_3 8.2.0 $VERSION #### Micro releases -For micro releases, GitHub API does not give good results because it uses PRs -while the backports are usually direct commits without PRs. -The *git log* command operates on commits, so use use the *log* backend: +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. +The _git log_ command operates on commits, so use use the _log_ backend: ```bash python ./utils/generate_release_notes.py log releasebranch_8_3 8.3.0 $VERSION @@ -189,7 +194,7 @@ python ./utils/generate_release_notes.py log releasebranch_8_3 8.3.0 $VERSION #### RCs -In between RCs and between last RC and final release, the *log* backend is useful +In between RCs and between last RC and final release, the _log_ backend is useful for showing updates since the last RC: ```bash @@ -199,13 +204,13 @@ python ./utils/generate_release_notes.py log releasebranch_8_3 8.3.0RC1 $VERSION #### Finalizing 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. +added manually to the result from the _api_ backend. -The script sorts them into categories defined in *utils/release.yml*. +The script sorts them into categories defined in _utils/release.yml_. However, these notes need to be manually edited to collapse related items into -one. Additionally, a *Highlights* section needs to be added with manually +one. Additionally, a _Highlights_ section needs to be added 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 +_Major_ section may need to be added showing critical fixes or breaking changes if there are any. ### Modify the release draft @@ -225,27 +230,27 @@ If RC, mark it as a pre-release, check: Save the modified draft, but do not publish the release yet. -## Reset include/VERSION file to git development version +## Update include/VERSION file Use the dedicated `update_version.py` script to edit the VERSION file. -After an RC, switch to development version: +After a RC, update to development version: ```bash ./utils/update_version.py dev ``` -Next switch back to the development version for the next micro, minor, -or major version, e.g., for micro version, use: +After a final release, update to the next micro (x.y.Z), minor (x.Y.z), +or major (X.y.y) version. E.g., for micro version, use: ```bash ./utils/update_version.py micro ``` -Use *major* and *minor* operations for the other version updates. +Use _major_ and _minor_ operations for the other version updates. Use `--help` for details about the options. -Commit with the suggested commit message and push, e.g.: +Eventually, commit with the suggested commit message and push, e.g.: ```bash git show @@ -253,18 +258,16 @@ git commit include/VERSION -m "..." 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): +## Publishing a final release -```bash -./utils/update_version.py suggest -``` +The published RC releases has the initial release notes (based on locally +auto-generated notes) which need to be refined further: -## Publish release +- add highlights +- verify that the subsections are well sorted -For the final release, edit the draft release again and publish it using the -"Publish release" button. +For the final release, edit these draft release again in order to publish it +using the "Publish release" button. ## Upload to OSGeo servers @@ -321,7 +324,7 @@ md5sum grass-${VERSION}.tar.gz > grass-${VERSION}.md5sum ### Upload source code tarball to OSGeo servers Note: servers 'osgeo7-grass' and 'osgeo7-download' only reachable via - jumphost (managed by OSGeo-SAC) - see +jumphost (managed by OSGeo-SAC) - see ```bash # Store the source tarball (twice) in (use scp -p FILES grass:): @@ -479,6 +482,22 @@ Subsequently, verify the software pages: - Create milestone and release: - Upload tarball for created release +### Update grass.osgeo.org + +These updates are for final releases only. + +Update version: + +- + +Add release article to news section: + +- + +Add release to history page: + +- + ### Other notes - @@ -506,24 +525,3 @@ Note: Do not use relative links. Via web and social media: - See: - -## Update VERSION file to next version number - -After the final release whole is done, modify the VERSION file use -the dedicated script, e.g., for next micro version, run: - -```bash -./utils/update_version.py micro -./utils/update_version.py status -``` - -Now commit the change to the branch with the commit message generated above -by the script: - -```bash -git diff -git commit include/VERSION -m "..." -``` - -If you lost the script output with the suggested message use -`./utils/update_version.py suggest` to get it.