From 8976f6da1be219b58eae95bd2500612ef67445bb Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Fri, 3 Jul 2026 09:57:40 -0700 Subject: [PATCH 1/2] Record develop-staleness and issue-closing learnings in AGENTS.md (#233) Two durable learnings from the CI/CD work: mirror main-only fixes to develop (and check git diff origin/develop origin/main before relying on develop), and put Closes #N in the promotion PR. No code changes. Co-authored-by: Claude Opus 4.8 (1M context) --- AGENTS.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index f7fba31..e6bd451 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,6 +19,8 @@ This is the developer-facing git policy. The branch rulesets that enforce it (me - **`develop` is forward-only**: no `main -> develop` back-merges. Historical back-merge commits in `git log` predate this rule and must not be repeated. - All commits on both branches are cryptographically signed (see Git and Commit Rules). Squash and merge commits created in the GitHub UI are signed by GitHub's web-flow key. - **Bots target both `main` and `develop` directly.** Dependabot and codegen open PRs against each branch independently. This is deliberate: running a bot on one branch and merging its changes across to the other causes endless conflicts as the feature -> develop -> main flow moves underneath it, whereas landing the same dependency or data update directly in each branch keeps bot changes conflict-free regardless of what else is in flight, and keeps the `main` package fresh without waiting on a promotion. Dependabot security PRs open against `main`. The mechanics (Dependabot's per-target-branch config, codegen's per-branch matrix) are in [`WORKFLOW.md`](./WORKFLOW.md) D8. +- **Mirror to `develop` any change that lands on `main` outside the feature -> develop -> main flow.** A reconciliation-branch fix made to resolve a `develop -> main` promotion conflict, or a security PR that merges only to `main`, leaves `develop` behind on that content - and forward-only `develop` never back-merges to catch up (the same parallel-target principle as the bots). Before basing new work on `develop`, or diagnosing a defect from it, check `git log origin/develop..origin/main`: any commits it lists are on `main` but not yet mirrored to `develop`, so `develop` is stale on that content and the defect may already be fixed on `main`. (A plain `git diff origin/develop origin/main` is not a staleness signal - it is normally non-empty because `develop` runs ahead of `main` between promotions.) +- **Put issue-closing keywords (`Closes #N`) where they fire on merge to the default branch (`main`).** GitHub closes an issue from a *PR description* only when that PR merges to `main`, so a `Closes #N` in a PR that targets `develop` never fires - put it in the `develop -> main` promotion PR instead. A closing keyword in a *commit message* does close the issue once that commit reaches `main` via promotion, but that is fragile across squash-merges, so prefer the promotion PR's description or close the issue manually once the fix lands on `main`. ## Release Model From 285a73809eba0f055fd416fa85b32a5442bf5218 Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Fri, 3 Jul 2026 10:01:52 -0700 Subject: [PATCH 2/2] Carry template upstream-drift reporting paragraph into copilot-instructions (#234) Closes the last substantive verbatim-carry gap found while auditing this repo against ptr727/ProjectTemplate for the convergence issues #160 and #176. ## What changed - `.github/copilot-instructions.md`: add the **"In a derived repo:"** paragraph from the template's "When in Doubt" section (verbatim), directing contributors to open an upstream issue in `ptr727/ProjectTemplate` when a discrepancy belongs in the template rather than only fixing it locally. ## Audit result (context) An audit of every item in #160 and #176 against the current template found nearly everything already converged: - **#160**: `.markdownlint-cli2.jsonc` byte-identical; `.editorconfig` line-ending rules fully converged; rulesets already lowercase `develop`/`main`. Done. - **#176**: consolidated `CODESTYLE.md` (General + .NET), `.NET`-cased tasks with `dependsOrder: sequence`, `retention-days: 1` on the release-asset upload, and `smoke`-gated build/upload are all present. The AGENTS.md rule updates (comments house-rule, markdown trailing backslash, versioning, CI storage) are present. Docker registry-cache guidance is N/A (no Docker workflow here). The only outstanding item was this one paragraph. Issue-closing keywords are intentionally omitted here (this PR targets `develop`); `Closes #160`/`Closes #176` will go on the `develop -> main` promotion PR so GitHub fires them on merge to the default branch. Co-authored-by: Claude Opus 4.8 (1M context) --- .github/copilot-instructions.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 49325b0..21f110c 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -150,3 +150,5 @@ After the final push, sweep-resolve stale older threads for removed code paths. ## When in Doubt Read [AGENTS.md](../AGENTS.md) for this repo's conventions. For code-style rules, [`CODESTYLE.md`](../CODESTYLE.md) (its General and .NET sections) is authoritative. Don't restate any of these files' rules in commit bodies or PR descriptions - keep those focused on the change itself. + +**In a derived repo:** if you find a discrepancy that should be fixed in the template itself (this file or AGENTS.md is out of date, a rule is missing, something bit this repo and would bite the next), open an issue upstream in [`ptr727/ProjectTemplate`](https://github.com/ptr727/ProjectTemplate) rather than only fixing it locally - see the template's [AGENTS.md "Staying in Sync and Reporting Drift Upstream"](https://github.com/ptr727/ProjectTemplate/blob/main/AGENTS.md#staying-in-sync-and-reporting-drift-upstream).