EOS/docs/develop/release.md

% SPDX-License-Identifier: Apache-2.0 (release-page)=

Release Process

This document describes how to prepare and publish a new release via a Pull Request from a fork, and how to set a development version after the release.

✅ Overview of the Process

Step	Actor	Action
1	Contributor	Prepare a release branch in your fork using Commitizen
2	Contributor	Open a Pull Request to upstream (Akkudoktor-EOS/EOS)
3	Maintainer	Review and merge the release PR
4	Maintainer	Create the GitHub Release and tag
5	Maintainer	Set the development version marker via a follow-up PR

🔄 Detailed Workflow

1️⃣ Contributor: Prepare the Release in Your Fork

Clone and sync your fork

git clone https://github.com/<your-username>/EOS
cd EOS
git remote add eos https://github.com/Akkudoktor-EOS/EOS

git fetch eos
git checkout main
git pull eos main

Create the release branch

git checkout -b release/vX.Y.Z

Bump the version information

At least update

• pyproject.toml
• src/akkudoktoreos/core/version.py
• src/akkudoktoreos/data/default.config.json
• Makefile

and the generated documentation:

make bump VERSION=0.1.0+dev NEW_VERSION=X.Y.Z
make gen-docs

You may check the changes by:

git diff

Create a new CHANGELOG.md entry

Edit CHANGELOG.md

Create the new release commit

git add pyproject.toml src/akkudoktoreos/core/version.py \
    src/akkudoktoreos/data/default.config.json Makefile CHANGELOG.md
git commit -s -m "chore(release): Release vX.Y.Z"

Push the branch to your fork

git push --set-upstream origin release/vX.Y.Z

2️⃣ Contributor: Open the Release Pull Request

From	To
<your-username>/EOS:release/vX.Y.Z	Akkudoktor-EOS/EOS:main

PR Title:

chore(release): release vX.Y.Z

PR Description Template:

## Release vX.Y.Z

This pull request prepares release **vX.Y.Z**.

### Changes
- Version bump
- Changelog update

### Changelog Summary
<!-- Copy key highlights from CHANGELOG.md here -->

See `CHANGELOG.md` for full details.

3️⃣ Maintainer: Review and Merge the Release PR

Review Checklist:

• ✅ Only version files and CHANGELOG.md are modified
• ✅ Version numbers are consistent
• ✅ Changelog is complete and properly formatted
• ✅ No unrelated changes are included

Merge Strategy:

• Prefer Merge Commit (or Squash Merge, per project preference)
• Use commit message: chore(release): Release vX.Y.Z

4️⃣ Maintainer: Publish the GitHub Release

1. Go to GitHub → Releases → Draft a new release
2. Choose tag → enter vX.Y.Z (GitHub creates the tag on publish)
3. Release title: vX.Y.Z
4. Paste changelog entry from CHANGELOG.md
5. Optionally enable Set as latest release
6. Click Publish release 🎉

5️⃣ Maintainer: Prepare the Development Version Marker

Sync local copy:

git fetch eos
git checkout main
git pull eos main

Create a development version branch:

git checkout -b release/vX.Y.Z_dev

Set development version marker manually:

make bump VERSION=X.Y.Z NEW_VERSION=X.Y.Z+dev
make gen-docs

git add pyproject.toml src/akkudoktoreos/core/version.py \
    src/akkudoktoreos/data/default.config.json Makefile
git commit -s -m "chore: set development version marker X.Y.Z+dev"

git push --set-upstream origin release/vX.Y.Z_dev

6️⃣ Maintainer (or Contributor): Open the Development Version PR

From	To
<your-username>/EOS:release/vX.Y.Z_dev	Akkudoktor-EOS/EOS:main

PR Title:

chore: development version vX.Y.Z+dev

PR Description Template:

## Development version vX.Y.Z+dev

This pull request marks the repository as back in active development.

### Changes
- Set version to `vX.Y.Z+dev`

No changelog entry is needed.

7️⃣ Maintainer: Review and Merge the Development Version PR

Checklist:

• ✅ Only version files updated to +dev
• ✅ No unintended changes

Merge Strategy:

• Merge with commit message: chore: development version vX.Y.Z+dev

✅ Quick Reference

Step	Actor	Action
1. Prepare release branch	Contributor	Bump version & changelog via Commitizen
2. Open release PR	Contributor	Submit release for review
3. Review & merge release PR	Maintainer	Finalize changes into main
4. Publish GitHub Release	Maintainer	Create tag & notify users
5. Prepare development version branch	Maintainer	Set development marker
6. Open development PR	Maintainer (or Contributor)	Propose returning to development state
7. Review & merge development PR	Maintainer	Mark repository as back in development