From cd2bb24d400249b5481cdcb39b3dd9295bfb9205 Mon Sep 17 00:00:00 2001 From: przemarzec <98286080+przemarzec@users.noreply.github.com> Date: Tue, 2 Jun 2026 23:54:55 +0200 Subject: [PATCH 1/3] chore(ci): switch release-trigger branch from main to dev semantic-release now fires on push to dev. main becomes a stable mirror that inherits the tagged release-commit via a regular forward-merge from dev after each release. This aligns the release flow across the project and removes the deviation in which main was the publisher branch. Files: - .releaserc.json: branches main -> dev - .github/workflows/release.yml: trigger main -> dev; publish job checkout ref main -> dev; header comment updated - CLAUDE.md: branching section rewritten so dev is the release-trigger and main is a stable mirror; direct release/* -> main is not used --- .github/workflows/release.yml | 15 ++++++++++----- .releaserc.json | 2 +- CLAUDE.md | 10 ++++++---- 3 files changed, 17 insertions(+), 10 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 788904e..4d5aabf 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -1,13 +1,18 @@ -# Single automated release pipeline — push to main. +# Single automated release pipeline — push to dev. # # semantic-release (the `release` job) owns versioning: it analyses the # Conventional-Commit history, bumps the version in pyproject.toml, updates # CHANGELOG.md, creates the git tag, and publishes the GitHub Release (via the # bundled @semantic-release/github plugin). It commits the bumped files back to -# main with [skip ci] so the pipeline does not re-trigger itself. +# dev with [skip ci] so the pipeline does not re-trigger itself. +# +# `dev` is the release-trigger branch (portfolio-wide convention). `main` is a +# stable mirror — it inherits the tagged release-commit via a separate forward +# merge from `dev` after each release. Regular-merge strategy on `dev → main` +# preserves SHA equality, so the tagged commit is reachable from both branches. # # When (and only when) semantic-release publishes a new version, the gated -# `publish` job checks out main HEAD (which now carries the bumped version), +# `publish` job checks out dev HEAD (which now carries the bumped version), # runs the smoke gate, builds the sdist + wheel, and uploads to PyPI via # trusted publishing (OIDC — no API token). # @@ -23,7 +28,7 @@ name: Release on: push: branches: - - main + - dev permissions: contents: write # create tags + releases @@ -99,7 +104,7 @@ jobs: - name: Checkout released commit uses: actions/checkout@v6 with: - ref: main + ref: dev fetch-depth: 0 - uses: actions/setup-python@v5 with: diff --git a/.releaserc.json b/.releaserc.json index 8e42d3a..ecc27db 100644 --- a/.releaserc.json +++ b/.releaserc.json @@ -1,5 +1,5 @@ { - "branches": ["main"], + "branches": ["dev"], "plugins": [ [ "@semantic-release/commit-analyzer", diff --git a/CLAUDE.md b/CLAUDE.md index 8bc6b77..c823b78 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -80,12 +80,14 @@ This repo follows a feature → release → integration → stable flow. | Branch | Role | |---|---| -| `main` | Stable, released. Tagged versions live here. | -| `dev` | Integration. Default PR target for features and fixes. | -| `release/v` | Release stabilisation. Created from `dev`, merged forward. | +| `dev` | Release-trigger and integration trunk. semantic-release runs on push to `dev` — the version tag `vX.Y.Z`, the release-commit (CHANGELOG + `pyproject.toml` bump), the PyPI artifact, and the GitHub Release are all created on `dev`. | +| `main` | Stable mirror. The branch users land on when cloning. After each release, `main` is forward-merged from `dev` with a regular merge so the tagged commit is reachable from both branches (same SHA). `main` never originates a release on its own. | +| `release/v` | Per-version stabilisation. Created from `main` (the last released state); accumulates one squash-commit per change; merged into `dev` to fire the release pipeline; then deleted. | | `/` | Feature / fix / chore branches. Plain English; no internal identifiers; ≤ 50 chars. | -Open PRs targeting `dev`. Branch names should describe the change in plain English (`feature/priority-signal-hybrid-search`, `fix/empty-count-on-mindql`, `docs/quickstart-update`). +Open PRs from your feature branch targeting the active `release/v` branch (or `dev` directly if no release branch is currently open). Branch names should describe the change in plain English (`feature/priority-signal-hybrid-search`, `fix/empty-count-on-mindql`, `docs/quickstart-update`). + +Direct merge from a `release/*` branch into `main` is not used in this repo — `main` is updated exclusively via forward-merge from `dev` after a release publishes. This keeps the tagged commit reachable from both branches and prevents `main` from drifting ahead of the publisher branch. ## Contributions From 76191270aa7abf26aaf33d15a938021f48b2a6f0 Mon Sep 17 00:00:00 2001 From: przemarzec <98286080+przemarzec@users.noreply.github.com> Date: Tue, 2 Jun 2026 23:55:10 +0200 Subject: [PATCH 2/3] docs(release): align branching guide with dev release-trigger model --- BRANCHING.md | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/BRANCHING.md b/BRANCHING.md index 966274f..afff9eb 100644 --- a/BRANCHING.md +++ b/BRANCHING.md @@ -1,15 +1,15 @@ # Branching — engrava -This repository uses a feature → integration → release → stable Git Flow. +This repository uses a feature → release → integration (release-trigger) → stable Git Flow: a change flows `feature/* → release/vX.Y.Z → dev → main`, with semantic-release firing on `dev`. ## Branches | Branch | Role | Who pushes | |---|---|---| -| `main` | Stable, tagged releases. Production-ready code. | Release process only | -| `dev` | Integration. Default PR target for features and fixes. | Maintainers (via PR) | -| `release/v` | Release stabilisation. Branched from `dev`, merged forward to `dev` + cherry-picked into `main` at release time. | Maintainers | +| `dev` | Release-trigger and integration trunk. Default PR target for features and fixes. semantic-release runs on push to `dev` — the version tag `vX.Y.Z`, the release commit, the published artifact, and the GitHub Release are all produced from `dev`. | Maintainers (via PR) | +| `main` | Stable mirror. Production-ready code; the branch users land on when cloning. After each release, `main` is forward-merged from `dev` (regular merge), so the tagged commit is reachable from both branches (same SHA). `main` never originates a release on its own. | Release process only (forward-merge from `dev`) | +| `release/v` | Per-version stabilisation. Branched from `main` (the last released state); accumulates one commit per change; merged into `dev` to fire the release; then deleted. | Maintainers | | `/` | Feature, fix, chore, docs branches. | Contributors | ## Feature / fix / chore branch naming @@ -36,27 +36,27 @@ This repository uses a feature → integration → release → stable Git Flow. │ fix/* │ │ docs/* │ └──────┬───────┘ - │ PR - ▼ - ┌──────────────┐ - │ dev │ integration - └──────┬───────┘ - │ release branch cut + │ PR (squash) ▼ ┌──────────────────┐ - │ release/vX.Y.Z │ stabilisation + │ release/vX.Y.Z │ per-version stabilisation (cut from main) └──────┬───────────┘ - │ release + tag + │ merge + ▼ + ┌──────────────┐ + │ dev │ release-trigger → semantic-release + │ vX.Y.Z tag │ (tag + publish created here) + └──────┬───────┘ + │ forward-merge (regular) ▼ ┌──────────────┐ - │ main │ stable - │ vX.Y.Z │ + │ main │ stable mirror (inherits the tagged commit) └──────────────┘ ``` ## Pull request expectations -- PRs target `dev` (not `main`). +- PRs target `dev` (not `main`). `main` is updated only by forward-merge from `dev` after a release — a `release/*` branch is never merged into `main` directly. - CI must be green before review. - Commits in the PR use Conventional Commits format. - Squash-merge by default unless a maintainer requests preserving commit history. From d28ace23b2ce74e482bb04ad3f2b0e96046657d6 Mon Sep 17 00:00:00 2001 From: przemarzec <98286080+przemarzec@users.noreply.github.com> Date: Tue, 2 Jun 2026 23:58:30 +0200 Subject: [PATCH 3/3] ci(ci): run CI on dev branch as well as main --- .github/workflows/ci.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ea6aa75..80ae685 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -2,9 +2,9 @@ name: CI on: push: - branches: [main] + branches: [main, dev] pull_request: - branches: [main] + branches: [main, dev] permissions: contents: read