From d1b4ad170d2382b3316dccb35710d7b5b9f767b4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hermes=20Rodr=C3=ADguez?= Date: Sat, 12 Sep 2026 13:30:17 -0400 Subject: [PATCH] =?UTF-8?q?Document=20topic-branch=20PRs=20and=20main?= =?UTF-8?q?=E2=86=92develop=20sync?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rulesets already protect develop/main; align AGENTS, CONTRIBUTING, and CHANGELOG with pgwd/gghstats. Branch tip includes main after #7. Co-authored-by: Cursor --- AGENTS.md | 5 +++-- CHANGELOG.md | 4 ++++ CONTRIBUTING.md | 5 ++++- 3 files changed, 11 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 40c8ab8..66a30df 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -36,7 +36,8 @@ Install tooling to `$GOBIN`: `make tools` (govulncheck, gocyclo). ## Git flow -- **Branches:** Day-to-day work on **`develop`**. Topic branch → **PR into `develop`** (green CI, merge, delete branch). Production: **PR `develop` → `main`**, then annotated tag **`v`** on **`main`** only. +- Work on **topic branches** opened from `develop`; merge via **PR into `develop`**. **Never** commit or push directly to `develop` or `main`. +- Release: **PR `develop` → `main`**, then annotated tag **`v`** on **`main`** only. After every merge into `main`, sync **`main` → `develop`** (see `.cursor/rules/git-flow.mdc` locally) so the next release PR is not **"out-of-date with the base branch"**. - **Never** merge to **`main`**, create/push a release tag, or run **`make release`** / trigger GoReleaser **without explicit user approval** in the current conversation — even if `release-check` is green. - **Commits:** Show the proposed commit message and wait for user approval before `git commit` (see `.cursor/rules/commit-message-review.mdc` locally). - **Language:** English only for code, comments, commit messages, docs, and UI strings. @@ -55,7 +56,7 @@ Do the **VERSION bump as a dedicated change on `develop`** after feature work la | 6 | **BSD ports** | `make port-freebsd-sync` and/or `make port-openbsd-sync` | | 7 | **`docs/ROADMAP.md`** | **Last reviewed** date; shipped highlights; tick completed bands | | 8 | **Gate** | `make release-check` — run only after user asks | -| 9 | **Ship** | Merge `develop` → `main`, annotated tag `v`, push tag — **only after user explicitly approves** | +| 9 | **Ship** | Open **PR `develop` → `main`**, merge on GitHub, annotated tag `v`, push tag — **only after user explicitly approves**. Then sync **`main` → `develop`**. | **Follow-ups (other repos, after GitHub Release is green):** pin app version in **[kzero-selfhosted](https://github.com/hrodrig/kzero-selfhosted)**; marketing/install sites on GitLab (`kzero-hermesrodriguez-com`, `get-kzero-hermesrodriguez-com`) if they hard-code a release. diff --git a/CHANGELOG.md b/CHANGELOG.md index da21c65..221485f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Changed + +- Branch policy matches pgwd / gghstats: topic branch → PR into `develop`; no direct push to `develop` or `main`. After `develop` → `main`, sync `main` into `develop` so the next release PR is not out-of-date. + [↑ Back to top](#top) ## [1.1.1] - 2026-09-02 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dfc1e3d..a0b052b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,9 @@ # Contributing -- Default branch for work: **`develop`**. **`main`** is production-ready; releases are tagged from `main` only (see [.cursor/rules/git-flow.mdc](.cursor/rules/git-flow.mdc) if present in your clone). +- **Branch policy:** `develop` is integration; `main` is production. Releases are tagged from `main` only. +- **Code:** From an up-to-date `develop`, create a **topic branch** (`feat/…`, `fix/…`, `chore/…`, `security/…`, `docs/…`), push it, and open a pull request **into `develop`**. Wait for green CI, then merge. +- **No direct push** to `develop` or `main` (GitHub rulesets `protect-develop` / `protect-main` — same pattern as [pgwd](https://github.com/hrodrig/pgwd) / [gghstats](https://github.com/hrodrig/gghstats)). +- **Release:** PR **`develop` → `main`**, then annotated tag `vX.Y.Z` on `main`. After every merge into `main`, sync **`main` → `develop`** so the next release PR is not **"out-of-date with the base branch"**. - Before opening a PR: **`make lint`**, **`make test`**, and **`make cover-check`** (total statement coverage must be **≥ 80%** unless you temporarily set `COVERAGE_MIN=` for a documented reason). - Before a release tag: **`make release-check`** (lint, tests, govulncheck, Grype on the built image — requires Docker). Sync **`contrib/man/man1/kzero.1`**: update **`.TH`** date and `kzero vX.Y.Z` to match **`VERSION`**, and document new CLI flags/commands; `release-check` fails if `.TH` version drifts.