Skip to content
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

doc: improve howto_release.md #5170

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
+48 −44
Open

doc: improve howto_release.md #5170

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
c93d0db
doc: improve howto_release.md
neteler Feb 21, 2025
63e7ad7
fix commit msg
neteler Feb 21, 2025
ed9c5c1
expand text on creating release draft
neteler Feb 24, 2025
3ec8729
sync VERSION file wording to utils/update_version.py
neteler Feb 24, 2025
9e4a6af
updated wget command to use correct URL
neteler Feb 24, 2025
b7f8f8f
Add the Zenodo badge to the release description
neteler Feb 25, 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
92 changes: 48 additions & 44 deletions doc/howto_release.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,11 +82,31 @@ 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 GIS 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)
```

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.

## Commit version

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

```bash
git diff
git commit include/VERSION -m "..."
git commit include/VERSION -m "version: GRASS GIS $VERSION"
```

If you lost the script output with the suggested message use
Expand All @@ -106,24 +126,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 Down Expand Up @@ -222,10 +224,10 @@ if there are any.
### Modify the release draft

After the automated release job completes, a new release draft will be available
in the GitHub web interface. You can copy-paste the created release notes to
GitHub and further modify as needed.

Older release description may or may not be a good inspiration:
in the [GitHub releases web interface](https://github.com/OSGeo/grass/releases).
You can copy-paste the locally created release notes to GitHub and further modify
in the web interface as needed, following the typical document structure.
Here, older release description may or may not be a good inspiration:
<https://github.com/OSGeo/grass/releases>.

If RC, mark it as a pre-release, check:
Expand All @@ -238,6 +240,14 @@ Save the modified draft, but do not publish the release yet.

## Update include/VERSION file

Save the current release version in a variable for later steps.
This will avoid confusion with the version number when switching
back in the VERSION file:

```bash
export REL_VERSION=$VERSION
```

Use the dedicated `update_version.py` script to edit the VERSION file.

After a RC, update to development version:
Expand All @@ -261,7 +271,7 @@ Eventually, commit with the suggested commit message and push, e.g.:
```bash
git show
eval $(./utils/update_version.py status --bash)
git commit include/VERSION -m "version: Back to $VERSION"
git commit include/VERSION -m "version: Start $VERSION"
Copy link
Member

Choose a reason for hiding this comment

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

The "Back to" versus "Start" is there for going from RC to the branch. Here is "version: Back to 8.4.1dev": 5890f9c

The correct commit message is generated by the script. That's why the version before current version had "..." and no eval (see b787bcc).

Copy link
Member Author

@neteler neteler Feb 25, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

Then let's solve it with a different variable.
Having "..." must be avoided - we want automation here and not manual copy-pasting by a (often tired) release manager :-) Manual copy-pasting is error-prone since the release procedure takes several hours in which the release manager does other tasks in parallel.

git push upstream
```

Expand Down Expand Up @@ -298,22 +308,16 @@ First, update the repo to get the tag locally:
git fetch upstream
```

Get the tagged source code, e.g. (modify the tag as needed):

```bash
git checkout 8.4.0RC1
```

Create the Bash variables for version numbers:
Verify the version (it should match exactly the tag specified above):

```bash
eval $(./utils/update_version.py status --bash)
echo "$REL_VERSION"
```

Confirm the version (it should match exactly the tag specified above):
Get the tagged source code, e.g. (modify the tag as needed):

```bash
echo "$VERSION"
git checkout $REL_VERSION
```

### Get changelog file for upload
Expand All @@ -323,17 +327,17 @@ fetch the file from the release which was generated by a workflow
linked to the tag:

```bash
wget https://github.com/OSGeo/grass/releases/download/${VERSION}/ChangeLog.gz \
-O ChangeLog_${VERSION}.gz
wget https://github.com/OSGeo/grass/releases/download/$REL_VERSION/ChangeLog.gz \
-O ChangeLog_$REL_VERSION.gz
```

### Get the source code tarball

Fetch a tarball from GitHub we also publish on OSGeo servers:

```bash
wget https://github.com/OSGeo/grass/archive/${VERSION}.tar.gz -O grass-${VERSION}.tar.gz
md5sum grass-${VERSION}.tar.gz > grass-${VERSION}.md5sum
wget https://github.com/OSGeo/grass/releases/download/$REL_VERSION/grass-$REL_VERSION.tar.gz
md5sum grass-$REL_VERSION.tar.gz > grass-$REL_VERSION.md5sum
```

### Upload source code tarball to OSGeo servers
Expand All @@ -354,19 +358,19 @@ eval $(ssh-agent) && ssh-add

# upload along with associated files, creating target dir if still needed
ssh $USER@$SERVER1 "mkdir -p $SERVER1DIR"
scp -p grass-$VERSION.* AUTHORS COPYING ChangeLog_$VERSION.gz \
scp -p grass-$REL_VERSION.* AUTHORS COPYING ChangeLog_$REL_VERSION.gz \
INSTALL.md REQUIREMENTS.md CONTRIBUTING.md $USER@$SERVER1:$SERVER1DIR

ssh $USER@$SERVER2 "mkdir -p $SERVER2DIR"
scp -p grass-$VERSION.* AUTHORS COPYING ChangeLog_$VERSION.gz \
scp -p grass-$REL_VERSION.* AUTHORS COPYING ChangeLog_$REL_VERSION.gz \
INSTALL.md REQUIREMENTS.md CONTRIBUTING.md $USER@$SERVER2:$SERVER2DIR

# Only at full release (i.e., not for RCs)!
# generate link to "latest" source code
ssh $USER@$SERVER1 "cd $SERVER1DIR ; rm -f grass-$MAJOR.$MINOR-latest.tar.gz"
ssh $USER@$SERVER1 "cd $SERVER1DIR ; ln -s grass-$VERSION.tar.gz grass-$MAJOR.$MINOR-latest.tar.gz"
ssh $USER@$SERVER1 "cd $SERVER1DIR ; ln -s grass-$REL_VERSION.tar.gz grass-$MAJOR.$MINOR-latest.tar.gz"
ssh $USER@$SERVER1 "cd $SERVER1DIR ; rm -f grass-$MAJOR.$MINOR-latest.md5sum"
ssh $USER@$SERVER1 "cd $SERVER1DIR ; ln -s grass-$VERSION.tar.md5sum grass-$MAJOR.$MINOR-latest.md5sum"
ssh $USER@$SERVER1 "cd $SERVER1DIR ; ln -s grass-$REL_VERSION.tar.md5sum grass-$MAJOR.$MINOR-latest.md5sum"

# verify
echo "https://grass.osgeo.org/grass$MAJOR$MINOR/source/"
Expand All @@ -375,7 +379,7 @@ echo "https://grass.osgeo.org/grass$MAJOR$MINOR/source/"
### Update redirects

For final minor and major releases (not release candidates and micro releases),
update `grass-stable` redirect at `osgeo7-grass`:
update `grass-stable` redirect at `osgeo8-grass`:

```bash
sudo vim /etc/apache2/sites-enabled/000-default.conf
Expand Down Expand Up @@ -430,7 +434,7 @@ Release is done.

For final releases only, go to [Zenodo](https://doi.org/10.5281/zenodo.5176030)
and get a Markdown badge for the release which Zenodo creates with a DOI
for the published release.
for the published release. Add the badge to the release description.

For all releases, click the Binder badge to get Binder to build. Use it to test
it and to cache the built image. Add more links to (or badges for) more notebooks
Expand Down
Loading