The Release Process¶

This page describes the release process for OSD Neo2. The process may look over-engineered for a small project like this one, but I’m used to it from my other projects like PyInstaller.

Preparation¶

Ensure you have write access to the repository at GitLab.
Install the required helper-tools:
```
pip install --user -U zest.releaser
```

Full Release Process¶

Prepare for Release¶

Prepare (see above).
Implement and close all issues and pull requests in a specific milestone.
Ensure everything relevant is committed and tested. git stash your local changes which should not go into the release.
Continuous integration tests should pass (if we have these tests)

Main Release Process¶

Set a shell variable to be able to copy-and-paste the remaining snippets, e.g.:
```
version=3.1
```
Create the release branch:
```
git checkout -b release/$version
```
Update versions in Source-code, Changelog, etc.:
```
prerelease # zest.releaser command
```
This will
- ask you a few questions - required version, …
- remove .devN from the version string
- update date and version in NEWS.rst

Update ``NEWS.rst``:

Where to look for possible changes? You can look in pull requests, issues, commits, mailing list or even OSD Neo2 cli options (new/removed options).
1. Check if the files are valid reStructuredText by running:
```
rst2html NEWS.rst > /tmp/NEWS.html
xdg-open /tmp/NEWS.html  # opens file in your web-browser
```
2. If everything is fine, commit:
```
git commit -m "Update NEWS.rst for release $version" NEWS.rst
```

Adjust whatever else is required for the release now.

Complete the release:

Merge into branch releases:

git checkout releases
git merge --no-ff -m "Release $version." release/$version

In case of a merge-conflict, resolve it using:

git gui # In the context-menu select "Use Local Version"
git commit -m "Finished release $version."

Tag and sign the release (we are using prefix v):
```
git tag -s v$version -m "|OSDNeo2| $version"
```

Do not run the zest.releaser script release. It will only perform stuff we do not need for this project.
Push the changes to GitLab:
```
git push --follow-tags origin releases
```
This will automatically create a new release and release archives under https://gitlab.com/htgoebel/OSD-Neo2/tags
Edit the release on GitLab:
1. Go to the |OSDNeo2| tags page
2. Edit the latest tag details.
3. Copy there the changelog for the current release. This should look like this one Mind to keep the links to the release archives and the different markup (which is markdown).

Update the website:
- Update version in conf.py.
- Update the link to the release archive in index.rst.
- Commit and push push the updated website:
```
git add conf.py
git commit -m "Bump version to $version"
git push
```
Announce the new release on:
- Neo-Layout mailing list

Post-Release Steps¶

Now we are going to perform some post-release steps:

Checkout the release-branch and forward it to releases:

git checkout release/$version releases
git reset --hard releases

Run the release script postrelease:
```
postrelease # zest.releaser command
```
This will
- increment version string for a new release: 3.0 -> 3.1.dev0
- prepare NEWS.rst for the next release.

Merge into branch develop:

git checkout main
git merge --no-ff -m "Finish releasing $version." release/$version

Check the diffs: it should only be version related stuff:
```
git diff origin/main
```
Delete the local release branch and push the changes:

git branch -d release/$version git push –follow-tags origin main releases