From 8872a75b3acb36ef0568036aac40c8a8a9372159 Mon Sep 17 00:00:00 2001 From: Jayapriya Pai Date: Mon, 10 Aug 2026 12:44:55 +0530 Subject: [PATCH 1/2] docs: document VERSION bump and upstream tag push in RELEASE.md Align the release guide with cut-PR practice so VERSION stays in sync with the GPG-signed tag pushed to rhobs/obs-mcp. Signed-off-by: Jayapriya Pai --- RELEASE.md | 46 +++++++++++++++++++++++++++++----------------- 1 file changed, 29 insertions(+), 17 deletions(-) diff --git a/RELEASE.md b/RELEASE.md index 8d11dfed..9e96c40b 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -9,7 +9,7 @@ This document describes how to create a new release of obs-mcp. ## Steps -### 1. Update CHANGELOG.md +### 1. Update CHANGELOG.md and VERSION Ensure main is up to date: @@ -20,14 +20,18 @@ git pull main --rebase Replace `` with the name of your upstream remote. Verify with `git remote -v`. -Create a branch, add a new section following the [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format: +Create a branch: ```bash -git checkout -b release-vX.Y.Z +git checkout -b cut-vX.Y.Z ``` +**Update `CHANGELOG.md`:** promote or add a versioned section following the [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format (typically move content from `[Unreleased]` into the new section and leave an empty `[Unreleased]`): + ```markdown -## [X.Y.Z] +## [Unreleased] + +## [vX.Y.Z] - YYYY-MM-DD ### Added - New feature description @@ -39,36 +43,43 @@ git checkout -b release-vX.Y.Z - Bug fix description ``` +**Update `VERSION`:** set the file to the release SemVer **without** the `v` prefix (for example `0.7.1`). This file is the version embedded by `make build`, `make build-linux`, and `make container`. It must match the git tag you create in step 2 (`v` + contents of `VERSION`). + +```bash +echo "X.Y.Z" > VERSION +``` + Commit and push to your fork: ```bash -git add CHANGELOG.md -git commit -m "docs: update changelog for vX.Y.Z" -git push release-vX.Y.Z +git add CHANGELOG.md VERSION +git commit -m "chore: cut vX.Y.Z" +git push cut-vX.Y.Z ``` Open a PR from your fork to upstream `main` and merge. -### 2. Create and push the tag +### 2. Create and push the tag (GPG-signed) -Pull the merged changelog into main: +Pull the merged release commit into main: ```bash git checkout main git pull main --rebase ``` -Verify tests pass: +Verify `VERSION` matches the release you intend to tag, then run tests: ```bash +cat VERSION # e.g. 0.7.1 → tag will be v0.7.1 make test-unit make lint ``` -Set the version and create a signed tag: +Create a **GPG-signed** annotated tag with the same version: ```bash -export VERSION=0.1.0 +export VERSION=$(cat VERSION) export TAG="v${VERSION}" make tag VERSION=${VERSION} ``` @@ -80,13 +91,14 @@ git verify-tag ${TAG} git log --oneline -5 # confirm the tag points to the expected commit ``` -Push the tag: +Push the tag to the **upstream** remote for the `rhobs` org (`rhobs/obs-mcp`), not your fork. Confirm with `git remote -v` (often named `upstream` or `origin` depending on your clone): ```bash -git push ${TAG} +git push ${TAG} +# e.g. git push upstream ${TAG} ``` -Pushing the tag triggers the [release workflow](.github/workflows/release.yaml), which: +Pushing the tag to upstream triggers the [release workflow](.github/workflows/release.yaml), which: - Runs unit tests - Builds cross-platform binaries (linux/darwin, amd64/arm64) via [GoReleaser](.goreleaser.yaml) @@ -118,11 +130,11 @@ Pre-releases follow the same process as stable releases but use the tag format ` ```bash git checkout main -git pull main --rebase +git pull main --rebase export VERSION=0.1.0-rc.1 export TAG="v${VERSION}" make tag VERSION=${VERSION} -git push ${TAG} +git push ${TAG} # rhobs/obs-mcp, not your fork ``` Pre-releases are marked as "pre-release" on GitHub and won't be considered the "latest" release. Use them to: From 670dffa9aeb7e6c2955313fd0c9bcada672e2397 Mon Sep 17 00:00:00 2001 From: Jayapriya Pai Date: Mon, 10 Aug 2026 12:52:53 +0530 Subject: [PATCH 2/2] docs: add patch release flow when main is ahead Document release-X.Y branches, cherry-pick PRs into the release line, and tagging from that branch so patches do not pick up unrelated main commits. Signed-off-by: Jayapriya Pai --- RELEASE.md | 124 ++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 119 insertions(+), 5 deletions(-) diff --git a/RELEASE.md b/RELEASE.md index 9e96c40b..a8826fb1 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -7,19 +7,21 @@ This document describes how to create a new release of obs-mcp. - A GPG key configured for signing git tags (`git config user.signingkey`) - Push access to the repository +Throughout this document, `` is the git remote for your fork (for example `fork`) and `` is the remote for `rhobs/obs-mcp` (for example `upstream`). Verify with `git remote -v`. + ## Steps +Use these steps for a release cut from current `main` (minor/major, or a patch when `main` *is* the tip you want to ship). If you need a **patch while `main` is ahead** with unrelated commits, use [Patch releases (when `main` is ahead)](#patch-releases-when-main-is-ahead) instead. + ### 1. Update CHANGELOG.md and VERSION Ensure main is up to date: ```bash git checkout main -git pull main --rebase +git pull main --rebase ``` -Replace `` with the name of your upstream remote. Verify with `git remote -v`. - Create a branch: ```bash @@ -54,7 +56,7 @@ Commit and push to your fork: ```bash git add CHANGELOG.md VERSION git commit -m "chore: cut vX.Y.Z" -git push cut-vX.Y.Z +git push cut-vX.Y.Z ``` Open a PR from your fork to upstream `main` and merge. @@ -65,7 +67,7 @@ Pull the merged release commit into main: ```bash git checkout main -git pull main --rebase +git pull main --rebase ``` Verify `VERSION` matches the release you intend to tag, then run tests: @@ -116,6 +118,118 @@ Pushing the tag to upstream triggers the [release workflow](.github/workflows/re - `checksums.txt` - `.bundle` signature files for each archive +## Patch releases (when `main` is ahead) + +Use this when you need a **patch** on an already shipped minor line (for example `v0.7.2` after `v0.7.1`) but `main` has moved on with other commits you do **not** want in that patch. + +The fix should already be (or also be) on `main`. You ship the patch from a **release branch**, cherry-picking only the commits required for the fix. + +### 1. Create or update the release branch + +Release branches are named `release-X.Y` (no `v` prefix), for example `release-0.7` for the `0.7.x` line. + +Fetch upstream and check whether the branch already exists: + +```bash +git fetch +git branch -r | grep "release-X.Y" || true +``` + +**If the branch does not exist**, create it from the last tag on that line and push it to upstream: + +```bash +# Example: patching the 0.7 line after v0.7.1 +export PREV_TAG=v0.7.1 +export RELEASE_BRANCH=release-0.7 + +git checkout -b ${RELEASE_BRANCH} ${PREV_TAG} +git push ${RELEASE_BRANCH} +``` + +**If the branch already exists**, check it out and update it: + +```bash +git checkout ${RELEASE_BRANCH} +git pull ${RELEASE_BRANCH} +``` + +### 2. Cherry-pick the fix from `main` + +The fix commit(s) should already be on `main`. You copy only those commits onto the release branch via a short-lived branch and a PR **whose base is `release-X.Y`**, not `main`. + +Example: shipping `v0.7.2` from `release-0.7`, cherry-picking commit `abc1234` from `main`. + +```bash +# Start from the release branch (already checked out / up to date from step 1) +git checkout -b cherry-pick-v0.7.2 + +# Find the fix on main, then cherry-pick it +git log --oneline main +git cherry-pick abc1234 +# If the commit is a merge commit: git cherry-pick -m 1 + +# Push this branch to your fork +git push cherry-pick-v0.7.2 +``` + +Open a pull request: + +| Field | Value | +| ----- | ----- | +| **base** (merge into) | `rhobs/obs-mcp` → `release-0.7` | +| **compare** (your branch) | `` → `cherry-pick-v0.7.2` | + +Do **not** target `main` for this PR. After it merges into `release-X.Y`, continue with the cut steps below on that release branch. + +### 3. Cut CHANGELOG.md and VERSION on the release branch + +After the cherry-pick PR is merged, update the release branch and open a cut PR (also targeting `release-X.Y`, not `main`): + +```bash +git checkout release-X.Y +git pull release-X.Y +git checkout -b cut-vX.Y.Z +``` + +- Add a `## [vX.Y.Z] - YYYY-MM-DD` section to `CHANGELOG.md` describing the patch (do **not** promote unrelated `[Unreleased]` content from `main`). +- Set `VERSION` to `X.Y.Z` (no `v` prefix). + +```bash +echo "X.Y.Z" > VERSION +git add CHANGELOG.md VERSION +git commit -m "chore: cut vX.Y.Z" +git push cut-vX.Y.Z +``` + +Open a pull request with **base** `release-X.Y` and **compare** `cut-vX.Y.Z`, then merge. + +If the changelog note for the patch should also appear on `main`, open a separate PR to `main` (or rely on the fix PR’s notes under `[Unreleased]`). + +### 4. Tag from the release branch (GPG-signed) + +```bash +git checkout release-X.Y +git pull release-X.Y + +cat VERSION +make test-unit +make lint + +export VERSION=$(cat VERSION) +export TAG="v${VERSION}" +make tag VERSION=${VERSION} +git verify-tag ${TAG} +git push ${TAG} # rhobs/obs-mcp, not your fork +``` + +Then verify the GitHub Release the same way as in [Steps → Verify the release](#3-verify-the-release). + +### Notes + +- Do **not** tag the patch from `main` if `main` contains commits beyond the release line. +- Keep `release-X.Y` around for further patches on that line; create it only once per minor line (from the previous tag) if missing. +- Minor/major releases from current `main` still follow [Steps](#steps) above (cut PR into `main`, then tag). + ## Manual release (via workflow dispatch) A release can also be triggered manually from the GitHub Actions UI: