Promote develop to main: CODESTYLE consolidation, Copilot runbook, CI quota by ptr727 · Pull Request #180 · ptr727/ProjectTemplate

ptr727 · 2026-06-22T18:12:52Z

Promote accumulated develop work to main so derived repos can re-sync from main (the stable ref) rather than tracking develop. Docs / CI / config only — no version.json bump (no functional change).

Notable contents

Consolidate code style + carry contract (Consolidate code style into one CODESTYLE.md and govern tasks #178, closesCODESTYLE.md carry contract is ambiguous and not derivation-neutral #175): one root CODESTYLE.md (General → .NET → Python, droppable sections); PyPiLibrary/CODESTYLE.md removed; CODESTYLE.md + .vscode/tasks.json added to the verbatim-carry list; official-tooling casing (.Net* → .NET*); clean-compile rule; brownfield/suppression scope hierarchy; dependsOrder: sequence on the .NET Format task.
Clarify project-rule home + harden Copilot runbook (Clarify that project-specific rules/API-contracts belong in AGENTS.md, not .github/copilot-instructions.md #173): project conventions/API contracts live in AGENTS.md, not .github/copilot-instructions.md; a no-inline-comment review is a clean pass; poll for the auto-review before self-triggering.
Cut Actions artifact-storage quota usage (Skip artifact uploads on PR smoke builds to cut quota usage #179): PR smoke builds no longer upload artifacts nothing consumes.
Plus prior develop work: docs/comment cleanup (Resummarize template docs and trim workflow comments #167), check-upstream-version-task structured multi-key state (check-upstream-version-task: structured multi-key JSON state #169) + CRLF state file (Write upstream-version state file as CRLF to honor the JSON rule #172), publish-docker-readme-task, and routine codegen updates.

Notes

develop → main is merge-commit only (preserves develop's commit list as a second-parent reference on main).
Merging closesClarify that project-specific rules/API-contracts belong in AGENTS.md, not .github/copilot-instructions.md #173 and CODESTYLE.md carry contract is ambiguous and not derivation-neutral #175 (their Closes keywords reach the default branch).
After merge, the downstream re-sync issues (each updated with the current state) can point at main.

This PR updates the codegen files. Co-authored-by: ptr727-codegen[bot] <275599072+ptr727-codegen[bot]@users.noreply.github.com>

…#156) ## Summary Three related template-contract fixes surfaced while re-syncing `ptr727/NxWitness` (NxWitness#439). ### 1. Resolve#155 — keep `.github/copilot-instructions.md` carry-safe (Option 2: decouple) The mandated whole-file verbatim carry embedded template-only assumptions that broke once carried into a conforming derived repo (whose only mandated AGENTS.md section is *PR Review Etiquette*): - Dropped the "what NOT to touch" / "files you must not touch" overstatements. - Removed the template-specific versioning paragraph (also clears the `#release-model` dangling anchor). - Replaced the pre-carry `<owner>/<repo>/<N>` blockquote with a clean runbook-purpose line (clears the `#files-and-sections…` dangling anchor). - Retargeted the staying-in-sync ref to an explicit upstream-template URL. Every remaining local `../AGENTS.md#` anchor now resolves only to the mandated `#pr-review-etiquette`. ### 2. Clarify versioning — remove the mandatory develop lead / post-release bump `version.json` is now bumped **only for functional changes, by maintainer instruction**, not mechanically after a release. `develop` builds are always prereleases, so they need no artificial minor lead and there is no `bump-version-X.Y` PR or `git checkout main -- version.json` trick. Updated AGENTS.md *Release Model* and the README branching bullet. ### 3. Add a Known Downstream Projects catalog New table in AGENTS.md *Staying in Sync* (NxWitness, PlexCleaner, Utilities, LanguageTags, ESPHome-NonRoot, VSCode-Server-DotNetCore, homeassistant-purpleair) with each repo's consumer model, plus the maintainer-facing direction to file heads-up issues downstream on contract changes — making the sync explicitly bidirectional. README points adopters to it and reinforces filing upstream issues. ## Verification - markdownlint-cli2 clean on all three files. - Old mechanical-lead rules grep-clean (only the new negation bullet remains). - All files remain fully CRLF; new anchors resolve.

This PR updates the codegen files. Co-authored-by: ptr727-codegen[bot] <275599072+ptr727-codegen[bot]@users.noreply.github.com>

Acts on the issues surfaced while porting ESPHome-NonRoot to the template (#157-#164), plus the comment/doc cleanup and CI-storage feedback. ## Docs - New **Comments house-rule** in AGENTS.md (concise, current-state, no cross-project references, no rule citations, match ~120-col) - applied throughout. - copilot-instructions.md resummarized: dropped the duplicated PR-title block and historic narrative, kept the Copilot review runbook mechanics. - Bless trailing-backslash hard line breaks (#164); clarify the cross-repo boundary (the template hub keeps the consistency/fan-out/Known-Downstream rules, derived repos never name siblings); simplify the `version.json` bump rule; document the HISTORY.md + README release-notes and CODESTYLE-aggregate patterns. ## Workflow comments (#162) - Trimmed ~300 comment lines across `.github/workflows/*`. Only comments changed (no logic), CRLF endings and action SHA-pins preserved. ## Doc-clarification issues - **#158** image tag is build-layer-owned; **#159** verbatim-vs-owned boundary in `test-pull-request.yml`; **#160** `.editorconfig` C# block marked .NET-only + first-time `.gitattributes` normalization; **#163** brownfield re-sign procedure rewritten (filter-branch + committer rewrite, ruleset ordering, API verification, cleanup). Also clarified that the maintainer-only force-push is restricted because it is destructive, not a signing concern. ## New reusable tasks - **#161** `publish-docker-readme-task.yml` + `Docker/README.md`, wired into `publish-release.yml`. - **#157** `check-upstream-version-task.yml` + `merge-upstream-version` wiring for wrapper repos that track an upstream release; state file standardized at the repo root. ## CI storage - `retention-days: 1` on all intermediate build artifacts (was 90-day default); documented the artifact-retention and registry-cache (`type=registry`, not `type=gha`) conventions. ## README - Added a **Deferred Patterns** backlog (unit-test factoring, per-language test scaffolds). Verified: actionlint clean, markdownlint clean, all touched `.yml`/`.md` CRLF, all actions SHA-pinned.

Closes#168. Raised by `ptr727/ESPHome-NonRoot` while re-syncing from #167: the canonical `check-upstream-version-task.yml` serialized only a single bare-string version, so a wrapper pinning **several** upstream components (ESPHome-NonRoot pins both `esphome` and the device-builder) could not converge on it and kept a bespoke tracker. ## Change - **Structured state file.** The resolver now prints a **JSON object of `name -> version`**; the task normalizes it (sorted keys, pretty) and writes it as the canonical state file. One key for the common single-version case (`{"version":"X"}`) or N keys for a multi-component wrapper, each read by the build by key. This also makes the `upstream-version.json` extension honest. - **Changed-key summary.** The bump PR title/body are diffed against the prior state and name **only the keys that actually moved**. The trivial single-`version` case still renders `Update upstream version to X`; multi-key renders `Update upstream versions: esphome to 2026.7.0` plus a per-component body list. - **Robustness.** Missing/corrupt state diffs cleanly against an empty object (first run works); a resolver that prints non-object output fails with a clear contract message; an unchanged object yields no diff so create-pull-request opens nothing. - **Docs.** `AGENTS.md` wrapper-repo description updated to the JSON `name -> version` contract. - **Workspace.** Swapped `gruntfuggly.todo-tree` for `fanaticpythoner.better-todo-tree` in `DotNet.code-workspace` (bundled per request). The merge-bot keys only on branch refs (`upstream-version-<base>`), so it needs no change. ## Validation Ran the resolve/compose logic locally across single-key first-run, multi-key first-run, partial move (one of two changed), no-change (empty diff → no PR), and malformed output (rejected). YAML validated. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Closes#170. Supersedes #171 (which took the wrong approach — see below). ## Problem `check-upstream-version-task.yml` wrote the state file with `printf '%s\n'` on the runner — **LF** — but `.editorconfig` defaults `.json`/`.jsonc` to **CRLF**. The committed `upstream-version.json` therefore contradicted the repo's own rule: open it in an `.editorconfig`-aware (or vanilla Windows) editor and save, and it flips to CRLF, so the next tracker run rewrites it back to LF — a spurious `Canonicalize upstream version state file` PR. ## Why not carve the file out to LF (the closed#171 / issue option 2) The whole point of defaulting JSON to CRLF is that **Windows vanilla-editor saves don't break things**. Carving the state file out to LF inverts that — a Windows save produces CRLF and now violates the carve-out, churning on exactly the platform the CRLF rule protects. So the fix belongs in the task, not in a special case. ## Fix (issue option 1) Write the state file with **CRLF**, honoring `.editorconfig`'s rule for `.json` with no per-file carve-out. `jq` emits LF, so convert line endings on write: ```sh printf '%s\n' "$new" | sed 's/$/\r/' > "$STATE_FILE" ``` `.editorconfig` and `.gitattributes` are untouched. ## Validation - Output is CRLF (`file` → `JSON text data`, `cat -A` → `^M$` line ends) and **idempotent**: rewriting identical content is byte-for-byte identical, so no churn / no spurious PR. - `jq -S '.'` still round-trips the CRLF file, so the old-state read and union diff are unaffected (comparison is on parsed objects, EOL-agnostic). - A Windows vanilla-editor save now produces CRLF that **matches** the committed file. - YAML parses. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Two template-doc gaps surfaced while re-syncing ptr727/LanguageTags. State that project-specific conventions and API/behavioral contracts belong in AGENTS.md (the agent-agnostic file every coding agent is directed to read), keeping .github/copilot-instructions.md narrow - the Copilot runbook plus the inline commit/PR-title summary. Harden the Copilot review runbook: a review with no inline comments is a completed clean pass, round 1 is auto-seeded and should be polled for before self-triggering, and the bot-id/seed decision keys on the formal review. Closes#173 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

This PR updates the codegen files. Co-authored-by: ptr727-codegen[bot] <275599072+ptr727-codegen[bot]@users.noreply.github.com>

PR smoke builds (test-pull-request.yml -> build-release-task.yml smoke:true) uploaded build artifacts that nothing consumes on a PR: github-release and the executable aggregation are gated !smoke, and publish-pypi runs only on a real publish. Those orphaned uploads churned the Actions artifact-storage quota on every target-touching PR. Gate the uploads on !inputs.smoke so smoke builds still compile/lint/test but persist nothing; publish runs (smoke:false) upload and consume as before: - build-nugetlibrary-task / build-pypilibrary-task: add a smoke input; skip the release-asset / wheel-sdist upload. - build-executable-task: skip the per-runtime publish-* matrix upload. - build-release-task: forward smoke to the nuget and pypi tasks. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Surfaced while re-syncing ptr727/Utilities; addresses the CODESTYLE carry-contract gaps in #175 plus related governance. - Merge PyPiLibrary/CODESTYLE.md into a single root CODESTYLE.md structured as General -> .NET -> Python, each language section droppable (the .editorconfig [*.cs] boundary model). CODESTYLE.md becomes a verbatim-carry artifact with marked adapt-zones and load-bearing repo-root placement. - General-section rules: official-tooling casing; a per-language clean-compile verification (named tasks/commands, carried verbatim, tasks.json is the canonical spec, run after every edit); and a suppression scope hierarchy where brownfield is never a license to relax severities. - Govern .vscode/tasks.json: rename labels .Net* -> .NET* (and launch.json), add dependsOrder: sequence to the .NET Format task, mark the clean-compile group carried-verbatim vs convenience/project-specific tasks. - Wire the carry contract and pointers through AGENTS.md, README, and .github/copilot-instructions.md. Admin-merged: the only failing check was the GitHub Actions artifact-storage quota (infra), not this change; unit tests, ruff/pyright/pytest, markdownlint, and the Copilot review all passed. Closes#175 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Promotes accumulated develop documentation and CI/governance updates to main, strengthening the template's carry contract (style guide consolidation + Copilot runbook) and reducing GitHub Actions artifact-quota usage.

Changes:

Consolidate code-style guidance into a single root CODESTYLE.md with a General section plus droppable per-language sections; remove PyPiLibrary/CODESTYLE.md and update carry-contract docs accordingly.
Harden/clarify the Copilot review runbook and template governance docs (including where project-specific rules belong).
Reduce Actions artifact storage churn on PR smoke builds (skip uploads with no consumers), and add reusable workflows for upstream-version tracking and Docker Hub README publishing.

Reviewed changes

Copilot reviewed 24 out of 24 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
README.md	Updates template adoption guidance, carry-contract checklist, and adds a deferred-patterns backlog section.
PyPiLibrary/CODESTYLE.md	Removes the per-language Python style guide (content moved into root `CODESTYLE.md`).
DotNet.code-workspace	Updates CSpell dictionary terms and replaces the TODO-tree extension recommendation.
Docker/README.md	Adds Docker Hub overview content for the console image (used by the Docker README publisher).
CODESTYLE.md	Becomes the single repo-wide style guide (General + droppable .NET/Python sections) and documents clean-compile/suppression rules.
CodeGen/CodeGen.cs	Updates the generated timestamp used by the codegen demo output.
AGENTS.md	Updates canonical style-guide pointers, carry-contract list (adds `CODESTYLE.md` and `.vscode/tasks.json`), and refines governance/runbook guidance.
.vscode/tasks.json	Renames `.Net` task labels to `.NET` and sets `.NET Format` dependencies to run sequentially.
.vscode/launch.json	Updates `preLaunchTask` references to the renamed `.NET Build` task label.
.github/workflows/test-pull-request.yml	Tightens/clarifies comments; documents orchestration-vs-owned boundaries for derived repos.
.github/workflows/run-periodic-codegen-pull-request.yml	Simplifies and clarifies scheduling/concurrency comments.
.github/workflows/run-codegen-pull-request-task.yml	Simplifies template-hygiene commentary while preserving the shared-runtime behavior.
.github/workflows/publish-release.yml	Adds a Docker Hub README publishing job and clarifies publish-plan/concurrency rationale.
.github/workflows/publish-docker-readme-task.yml	Introduces a reusable task that publishes `Docker/README.md` to Docker Hub on `main`.
.github/workflows/merge-bot-pull-request.yml	Adds auto-merge support for upstream-version bump PRs and condenses existing workflow rationale.
.github/workflows/get-version-task.yml	Condenses the rationale for floating `dotnet/nbgv@master` while preserving the behavior.
.github/workflows/check-upstream-version-task.yml	Adds a reusable upstream-version tracker that normalizes state and opens rolling bump PRs.
.github/workflows/build-release-task.yml	Forwards `smoke` to leaf tasks and documents skipping smoke-only artifact uploads.
.github/workflows/build-pypilibrary-task.yml	Adds `smoke` input and skips artifact uploads on smoke builds; adds retention-days for artifacts.
.github/workflows/build-nugetlibrary-task.yml	Adds `smoke` input and skips release-asset artifact creation/uploads on smoke builds; adds retention-days.
.github/workflows/build-executable-task.yml	Skips per-runtime artifact uploads on smoke builds; adds retention-days for artifacts.
.github/workflows/build-docker-task.yml	Comment consolidation/clarification without changing core build logic.
.github/copilot-instructions.md	Keeps the file narrow (commit/PR-title summary + Copilot runbook) and clarifies clean-pass review semantics.
.editorconfig	Annotates the .NET-only boundary and adds suppression guidance pointing to `CODESTYLE.md`.

ptr727 · 2026-06-22T18:12:52Z

Promote accumulated develop work to main so derived repos can re-sync from main (the stable ref) rather than tracking develop. Docs / CI / config only — no version.json bump (no functional change).

Notable contents

Consolidate code style + carry contract (Consolidate code style into one CODESTYLE.md and govern tasks #178, closesCODESTYLE.md carry contract is ambiguous and not derivation-neutral #175): one root CODESTYLE.md (General → .NET → Python, droppable sections); PyPiLibrary/CODESTYLE.md removed; CODESTYLE.md + .vscode/tasks.json added to the verbatim-carry list; official-tooling casing (.Net* → .NET*); clean-compile rule; brownfield/suppression scope hierarchy; dependsOrder: sequence on the .NET Format task.
Clarify project-rule home + harden Copilot runbook (Clarify that project-specific rules/API-contracts belong in AGENTS.md, not .github/copilot-instructions.md #173): project conventions/API contracts live in AGENTS.md, not .github/copilot-instructions.md; a no-inline-comment review is a clean pass; poll for the auto-review before self-triggering.
Cut Actions artifact-storage quota usage (Skip artifact uploads on PR smoke builds to cut quota usage #179): PR smoke builds no longer upload artifacts nothing consumes.
Plus prior develop work: docs/comment cleanup (Resummarize template docs and trim workflow comments #167), check-upstream-version-task structured multi-key state (check-upstream-version-task: structured multi-key JSON state #169) + CRLF state file (Write upstream-version state file as CRLF to honor the JSON rule #172), publish-docker-readme-task, and routine codegen updates.

Notes

develop → main is merge-commit only (preserves develop's commit list as a second-parent reference on main).
Merging closesClarify that project-specific rules/API-contracts belong in AGENTS.md, not .github/copilot-instructions.md #173 and CODESTYLE.md carry contract is ambiguous and not derivation-neutral #175 (their Closes keywords reach the default branch).
After merge, the downstream re-sync issues (each updated with the current state) can point at main.