Skip to content

docs: update release process for develop-targeted flow #69

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

Merged
JeanPhilippeKernel merged 2 commits into from
Aug 24, 2026
Merged

docs: update release process for develop-targeted flow #69

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ccbd9e1
docs: update release process for develop-targeted flow
JeanPhilippeKernel Aug 24, 2026
02a398c
ci: trigger re-run with updated skip workflow
JeanPhilippeKernel Aug 24, 2026
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
86 changes: 31 additions & 55 deletions docs/release-process.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,91 +1,67 @@
# Release Process

Panzerfaust uses two branches and [Release Please](https://github.com/googleapis/release-please) to automate versioning and publishing.

| Branch | Track | Example tag |
|---|---|---|
| `develop` | Pre-release (RC) | `v1.2.0-rc.1` |
| `main` | Stable | `v1.2.0` |

All automation is driven by [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). No manual version bumping.
Panzerfaust uses [Release Please](https://github.com/googleapis/release-please) and [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) to automate versioning and publishing. All releases — RC and stable — are driven from `develop`. No manual version bumping, no develop → main merge dance.

---

## Day-to-day development
## Branches

Contributors open PRs against `develop`. Once merged, Release Please on `develop` automatically opens or updates a **Pre-release PR** that accumulates the pending version bump and changelog entries.
| Branch | Purpose |
|---|---|
| `develop` | Default branch. All development, all releases. |
| `main` | Read-only mirror of the last stable release. Updated manually after each stable if desired. |

---

## Cutting a pre-release (RC)

1. Review the open Release Please PR on `develop` (titled `chore: release X.Y.Z-rc.N`).
2. Check the changelog entries look correct.
3. Merge the PR.
## Day-to-day development

Release Please then:
- Bumps `VERSION.txt` to e.g. `1.2.0-rc.1`
- Creates tag `v1.2.0-rc.1`
- Publishes a GitHub Pre-release with build artifacts for all platforms
Open PRs against `develop`. Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) in your PR title:

Subsequent merges to `develop` before a stable release increment the counter: `rc.1` → `rc.2` → …
```
feat(scope): add something new → minor bump
fix(scope): correct a bug → patch bump
feat!: breaking change → major bump
ci/docs/chore: housekeeping → no bump
```

---

## Promoting to stable

Once `develop` is ready to ship:

1. Open a PR from `develop` → `main`.
2. Get it reviewed and merge it.
3. Release Please on `main` opens a **Stable Release PR** (titled `chore: release X.Y.Z`).
4. Review and merge that PR.
## Cutting a pre-release (RC)

Release Please then:
- Bumps `VERSION.txt` to e.g. `1.2.0`
- Creates tag `v1.2.0`
- Publishes a GitHub Release (stable) with build artifacts
The pre-release pipeline runs automatically on every push to `develop`. No action needed — if the push contains releasable commits, a new `vX.Y.Z-rc.N` tag is created and a GitHub Pre-release is published with build artifacts.

---

## Syncing `develop` after a stable release
## Cutting a stable release

After the stable Release PR merges to `main`, `develop` is behind by the version bump commit. Sync it:
1. Review the open Release Please PR on `develop` (titled `chore: release X.Y.Z`).
2. Check the changelog looks correct.
3. Merge the PR.

```sh
git checkout develop
git fetch origin
git merge origin/main
git push origin develop
```
Release Please then:
- Bumps `VERSION.txt` and `Panzerfaust.csproj` to `X.Y.Z`
- Updates `CHANGELOG.md`
- Creates tag `vX.Y.Z` on `develop`
- Publishes a GitHub Release with artifacts for Windows, macOS arm64, and Linux

This keeps `VERSION.txt` and `CHANGELOG.md` consistent on both branches.
That's it. No other steps required.

---

## Hotfix on stable
## Hotfix

For urgent fixes that cannot wait for the next RC cycle:

1. Branch off `main`: `git checkout -b fix/<description> main`
1. Branch off `develop`: `git checkout -b fix/<description> develop`
2. Apply the fix with a `fix:` commit.
3. Open a PR against `main` directly.
4. Merge — Release Please opens a patch release PR (`v1.2.1`).
5. Merge the release PR.
6. Back-port to `develop`:

```sh
git checkout develop
git cherry-pick <fix-commit-sha>
git push origin develop
```
3. Open a PR against `develop`.
4. Merge — Release Please updates the pending release PR with the fix.
5. Merge the Release Please PR to ship the patch release.

---

## Version bump rules

The version bump is determined automatically from commit types since the last release:

| Commit type | Bump |
|---|---|
| `feat` | minor |
Expand Down