From 00cd6204c47f62da22924c3f3d517880be11d81c Mon Sep 17 00:00:00 2001
From: alphacrack <18480504+alphacrack@users.noreply.github.com>
Date: Thu, 30 Jul 2026 23:43:13 +0200
Subject: [PATCH] docs: single-trunk on main; drop stale development-branch
 guidance
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Contributors were being sent to a dead branch. CONTRIBUTING.md,
CLAUDE.md, and the PR template all told people to branch from and
target `development`, but that branch has been frozen ~27 commits
behind `main` since the v0.4.0 era — everything actually ships from
`main` (which is now protected with required CI + review).

This misdirection directly caused PRs #68, #69, and #70 (all three
first-time-contributor PRs open right now) to be cut from a stale base,
show 60+ unrelated files, and become unmergeable.

Changes:
- CONTRIBUTING.md: branch from / target `main`; add a fork-sync snippet
  and a 'if your PR shows dozens of files, rebase' note.
- PULL_REQUEST_TEMPLATE.md: target `main`; checklist item now asks the
  author to confirm the branch is rebased on current main.
- CLAUDE.md: state that main is the single trunk.

Follow-up (separate, maintainer action): delete the `development`
branch now that no docs point at it.

Signed-off-by: alphacrack <18480504+alphacrack@users.noreply.github.com>
---
 .github/PULL_REQUEST_TEMPLATE.md |  4 ++--
 CLAUDE.md                        |  2 +-
 CONTRIBUTING.md                  | 16 +++++++++++++---
 3 files changed, 16 insertions(+), 6 deletions(-)

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index a92297b..067ff0c 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1,7 +1,7 @@
 <!--
 Thanks for the PR! A quick guide:
 
-- PRs target `development`, not `main`. See CONTRIBUTING.md.
+- PRs target `main` (the single trunk). Branch from an up-to-date `main`. See CONTRIBUTING.md.
 - Sign off commits with `git commit -s` (DCO required).
 - Update CHANGELOG.md under `## [Unreleased]` for any user-visible change.
 - The `.github/labeler.yml` will auto-label `area:*` based on paths you
@@ -34,7 +34,7 @@ Preferred order: failing repro pre-fix → passing test post-fix → any manual
 
 ## Checklist
 
-- [ ] Targets `development` (not `main`).
+- [ ] Targets `main`, and the branch is rebased on current `main` (diff shows only your files).
 - [ ] Commits are DCO-signed (`git commit -s`).
 - [ ] `ruff check src/ tests/` and `ruff format --check src/ tests/` clean.
 - [ ] `mypy src/iac_scanner` clean (CI is `--strict`).
diff --git a/CLAUDE.md b/CLAUDE.md
index ed2fa4c..d56c18d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -73,7 +73,7 @@ Content-addressed (SHA-256 over `call_kind + raw_content + provider + model + pr
 ## Conventions worth knowing
 
 - **mypy is strict** (`disallow_untyped_defs`, `warn_unused_ignores`, etc.). CI hard-fails on any issue. Annotate fully.
-- **PRs target `development`**, not `main`. Sign off with `git commit -s` (DCO required).
+- **`main` is the single trunk.** PRs target `main` (protected: required CI + review); there is no long-lived `development` branch. Sign off with `git commit -s` (DCO required).
 - **Test markers** must be one of `smoke`, `integration`, `e2e` (declared in `pyproject.toml`; `--strict-markers` is on). `e2e` only runs in the nightly workflow.
 - **Mocking the LLM**: use `FakeLLMClient` from `tests/conftest.py` and the `fake_analysis_client_*` / `fake_fix_client_*` fixtures. Do not hit real providers in unit tests. `isolate_cache_dir` and `clear_llm_env` fixtures are autouse, so tests get a clean cache + scrubbed env automatically.
 - **Bandit** skips `B101` (assert in pytest) and `B310` (urlopen — guarded upstream). Don't broaden the skiplist without justification.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 906af58..25e67e7 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -15,11 +15,21 @@ See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) (Contributor Covenant 2.1). Report
 ## How to contribute
 
 1. **Open an issue** (bug or feature) so we can align before you invest time.
-2. **Fork the repo** and create a branch from `development`: `git checkout -b fix/your-change`.
+2. **Fork the repo** and create a branch from **`main`** (make sure your fork is up to date first — see below): `git checkout -b fix/your-change`.
 3. **Make your changes** and run locally (see [Development setup](#development-setup)).
-4. **Push and open a Pull Request** targeting `development`. CI must pass.
+4. **Push and open a Pull Request** targeting **`main`**. CI must pass.
 5. **Sign off** commits with `-s` so DCO is satisfied (`git commit -s -m "..."`).
 
+> **`main` is the single trunk.** There is no long-lived `development` branch — everything (features, fixes, releases) lands on `main`, which is protected (required CI + review). Before branching, sync your fork so you don't start from a stale base:
+>
+> ```bash
+> git remote add upstream https://github.com/alphacrack/iac-scanner.git   # one-time
+> git fetch upstream
+> git checkout -b fix/your-change upstream/main
+> ```
+>
+> If a PR ever shows dozens of unrelated files, your branch was cut from an old base — rebase it: `git fetch upstream && git rebase upstream/main && git push --force-with-lease`.
+
 ---
 
 ## Development setup
@@ -93,7 +103,7 @@ The project blog and tutorial live in [docs/](docs/) and are published via GitHu
 We use **Semantic Versioning** (`vMAJOR.MINOR.PATCH`). Tags are the source of truth — there are no version bumps in source files to forget.
 
 1. Make sure every user-visible change is in `## [Unreleased]` in [CHANGELOG.md](CHANGELOG.md).
-2. From a clean `main` (or `development` if that is the release branch), run:
+2. From a clean, up-to-date `main`, run:
    ```bash
    make release-patch     # or release-minor / release-major
    # preview first: