Resummarize template docs and trim workflow comments by ptr727 · Pull Request #167 · ptr727/ProjectTemplate

ptr727 · 2026-06-21T15:12:10Z

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 (Markdown convention: 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

build-docker-task hardcodes the image tag to SemVer2; wrapper repos need an external version #158 image tag is build-layer-owned; Clarify which parts of test-pull-request.yml are verbatim vs owned (unit-test job is .NET-coupled) #159 verbatim-vs-owned boundary in test-pull-request.yml; .editorconfig verbatim carry mixes line-ending governance with a large C#-only style block #160.editorconfig C# block marked .NET-only + first-time .gitattributes normalization; Brownfield re-sign: recommend filter-branch + committer rewrite, and clarify ruleset-blocking/ordering #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

Promote a Docker Hub README task (publish-docker-readme-task.yml) into the template #161publish-docker-readme-task.yml + Docker/README.md, wired into publish-release.yml.
Promote an upstream-dependency-version-tracker pattern into the template #157check-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.

Act on the issues surfaced porting ESPHome-NonRoot to the template, plus the comment/doc cleanup feedback. Docs: - Add a Comments house-rule (concise, current-state, no cross-project references, no rule citations, match ~120-col) and apply it. - Trim ~300 comment lines across .github/workflows/*; only comments changed (no logic), CRLF and SHA-pins preserved. - Resummarize copilot-instructions.md (drop duplicated PR-title block, historic narrative) keeping the Copilot runbook mechanics. - Bless trailing-backslash hard line breaks; clarify the cross-repo boundary (hub keeps the registry/fan-out rules, derived repos never name siblings); simplify the version.json rule; document HISTORY.md + CODESTYLE aggregate patterns. Workflows and CI: - Mark the .editorconfig C# block .NET-only; note first-time .gitattributes normalization. - Rewrite the brownfield re-sign procedure (filter-branch + committer rewrite, ruleset ordering, API verification, cleanup); clarify the maintainer-only force-push is restricted as a destructive operation, not a signing concern. - Ship publish-docker-readme-task.yml + Docker/README.md, wired into publish-release.yml. - Ship check-upstream-version-task.yml + merge-bot wiring for wrapper repos that track an upstream release. - Set retention-days: 1 on intermediate build artifacts and document the artifact-retention and registry-cache storage conventions. Add a Deferred Patterns backlog to the README.

Copilot

Pull request overview

This PR updates the ProjectTemplate documentation and GitHub Actions workflows to reflect lessons learned during downstream porting, focusing on clearer template/derived-repo boundaries, more concise current-state comments, and new reusable scaffolding for common downstream patterns.

Changes:

Refines core docs (AGENTS.md, README.md, copilot instructions) to add a comments house rule, clarify markdown hard-break conventions, and document derived-repo carry/ownership boundaries.
Trims and modernizes workflow comments across CI/release/codegen/merge-bot workflows without intended behavior changes, and documents CI artifact-retention/cache conventions.
Adds reusable workflows and docs for Docker Hub README publishing and upstream-version tracking (wrapper-repo pattern), plus wiring in publish/merge automation.

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
README.md	Adds a deferred-patterns section and clarifies derived-repo adoption guidance (incl. .gitattributes normalization).
DotNet.code-workspace	Updates workspace spellcheck/word allowlist.
Docker/README.md	Adds a Docker Hub repository overview README for the published image.
AGENTS.md	Adds comments house rules; clarifies test-pull-request ownership boundaries; documents artifact retention/cache guidance; adds wrapper-repo upstream-version tracker pattern.
.github/workflows/test-pull-request.yml	Trims/reshapes explanatory comments and clarifies unit-test job ownership for non-.NET repos.
.github/workflows/run-periodic-codegen-pull-request.yml	Trims schedule/concurrency commentary.
.github/workflows/run-codegen-pull-request-task.yml	Trims/modernizes comments; preserves codegen mechanics.
.github/workflows/publish-release.yml	Trims comments and wires in Docker Hub README publishing task.
.github/workflows/publish-docker-readme-task.yml	New reusable task to push Docker/README.md to Docker Hub.
.github/workflows/merge-bot-pull-request.yml	Adds auto-merge support for upstream-version bump PRs; trims header commentary.
.github/workflows/get-version-task.yml	Trims commentary around inputs/outputs and nbgv pin rationale.
.github/workflows/check-upstream-version-task.yml	New reusable task for wrapper repos to track upstream versions and open rolling bump PRs.
.github/workflows/build-release-task.yml	Trims and clarifies comments for orchestration/build seam and publishing invariants.
.github/workflows/build-pypilibrary-task.yml	Trims comments and sets short retention on build artifacts.
.github/workflows/build-nugetlibrary-task.yml	Trims comments and sets short retention on release-asset artifacts.
.github/workflows/build-executable-task.yml	Trims comments and sets short retention on intermediate/release artifacts.
.github/workflows/build-docker-task.yml	Trims comments (no intended logic changes) and clarifies cache/login rationale.
.github/copilot-instructions.md	Resummarizes/condenses the Copilot instructions while keeping the runbook mechanics.
.editorconfig	Marks the C# style block as .NET-only and clarifies the always-verbatim EOL governance block.

- Pin the docker-readme checkout to inputs.branch so the main leg always publishes main's readme regardless of the triggering ref. - Clarify that bump-branch-prefix must match the merge-bot's hard-coded upstream-version-<base> head refs or auto-merge won't fire. - Document that Docker immutable tags are NBGV SemVer2, including develop prerelease tags, not only X.Y.Z.

Copilot

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated 2 comments.

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>

… quota (#180) 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** (#178, closes#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** (#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** (#179): PR smoke builds no longer upload artifacts nothing consumes. - Plus prior develop work: docs/comment cleanup (#167), `check-upstream-version-task` structured multi-key state (#169) + CRLF state file (#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 closes#173 and #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`.

ptr727 · 2026-06-21T15:12:10Z

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 (Markdown convention: 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

build-docker-task hardcodes the image tag to SemVer2; wrapper repos need an external version #158 image tag is build-layer-owned; Clarify which parts of test-pull-request.yml are verbatim vs owned (unit-test job is .NET-coupled) #159 verbatim-vs-owned boundary in test-pull-request.yml; .editorconfig verbatim carry mixes line-ending governance with a large C#-only style block #160.editorconfig C# block marked .NET-only + first-time .gitattributes normalization; Brownfield re-sign: recommend filter-branch + committer rewrite, and clarify ruleset-blocking/ordering #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

Promote a Docker Hub README task (publish-docker-readme-task.yml) into the template #161publish-docker-readme-task.yml + Docker/README.md, wired into publish-release.yml.
Promote an upstream-dependency-version-tracker pattern into the template #157check-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.

Act on the issues surfaced porting ESPHome-NonRoot to the template, plus the comment/doc cleanup feedback. Docs: - Add a Comments house-rule (concise, current-state, no cross-project references, no rule citations, match ~120-col) and apply it. - Trim ~300 comment lines across .github/workflows/*; only comments changed (no logic), CRLF and SHA-pins preserved. - Resummarize copilot-instructions.md (drop duplicated PR-title block, historic narrative) keeping the Copilot runbook mechanics. - Bless trailing-backslash hard line breaks; clarify the cross-repo boundary (hub keeps the registry/fan-out rules, derived repos never name siblings); simplify the version.json rule; document HISTORY.md + CODESTYLE aggregate patterns. Workflows and CI: - Mark the .editorconfig C# block .NET-only; note first-time .gitattributes normalization. - Rewrite the brownfield re-sign procedure (filter-branch + committer rewrite, ruleset ordering, API verification, cleanup); clarify the maintainer-only force-push is restricted as a destructive operation, not a signing concern. - Ship publish-docker-readme-task.yml + Docker/README.md, wired into publish-release.yml. - Ship check-upstream-version-task.yml + merge-bot wiring for wrapper repos that track an upstream release. - Set retention-days: 1 on intermediate build artifacts and document the artifact-retention and registry-cache storage conventions. Add a Deferred Patterns backlog to the README.

Copilot

Pull request overview

This PR updates the ProjectTemplate documentation and GitHub Actions workflows to reflect lessons learned during downstream porting, focusing on clearer template/derived-repo boundaries, more concise current-state comments, and new reusable scaffolding for common downstream patterns.

Changes:

Refines core docs (AGENTS.md, README.md, copilot instructions) to add a comments house rule, clarify markdown hard-break conventions, and document derived-repo carry/ownership boundaries.
Trims and modernizes workflow comments across CI/release/codegen/merge-bot workflows without intended behavior changes, and documents CI artifact-retention/cache conventions.
Adds reusable workflows and docs for Docker Hub README publishing and upstream-version tracking (wrapper-repo pattern), plus wiring in publish/merge automation.

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
README.md	Adds a deferred-patterns section and clarifies derived-repo adoption guidance (incl. .gitattributes normalization).
DotNet.code-workspace	Updates workspace spellcheck/word allowlist.
Docker/README.md	Adds a Docker Hub repository overview README for the published image.
AGENTS.md	Adds comments house rules; clarifies test-pull-request ownership boundaries; documents artifact retention/cache guidance; adds wrapper-repo upstream-version tracker pattern.
.github/workflows/test-pull-request.yml	Trims/reshapes explanatory comments and clarifies unit-test job ownership for non-.NET repos.
.github/workflows/run-periodic-codegen-pull-request.yml	Trims schedule/concurrency commentary.
.github/workflows/run-codegen-pull-request-task.yml	Trims/modernizes comments; preserves codegen mechanics.
.github/workflows/publish-release.yml	Trims comments and wires in Docker Hub README publishing task.
.github/workflows/publish-docker-readme-task.yml	New reusable task to push Docker/README.md to Docker Hub.
.github/workflows/merge-bot-pull-request.yml	Adds auto-merge support for upstream-version bump PRs; trims header commentary.
.github/workflows/get-version-task.yml	Trims commentary around inputs/outputs and nbgv pin rationale.
.github/workflows/check-upstream-version-task.yml	New reusable task for wrapper repos to track upstream versions and open rolling bump PRs.
.github/workflows/build-release-task.yml	Trims and clarifies comments for orchestration/build seam and publishing invariants.
.github/workflows/build-pypilibrary-task.yml	Trims comments and sets short retention on build artifacts.
.github/workflows/build-nugetlibrary-task.yml	Trims comments and sets short retention on release-asset artifacts.
.github/workflows/build-executable-task.yml	Trims comments and sets short retention on intermediate/release artifacts.
.github/workflows/build-docker-task.yml	Trims comments (no intended logic changes) and clarifies cache/login rationale.
.github/copilot-instructions.md	Resummarizes/condenses the Copilot instructions while keeping the runbook mechanics.
.editorconfig	Marks the C# style block as .NET-only and clarifies the always-verbatim EOL governance block.

- Pin the docker-readme checkout to inputs.branch so the main leg always publishes main's readme regardless of the triggering ref. - Clarify that bump-branch-prefix must match the merge-bot's hard-coded upstream-version-<base> head refs or auto-merge won't fire. - Document that Docker immutable tags are NBGV SemVer2, including develop prerelease tags, not only X.Y.Z.

Copilot

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated 2 comments.

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>

… quota (#180) 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** (#178, closes#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** (#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** (#179): PR smoke builds no longer upload artifacts nothing consumes. - Plus prior develop work: docs/comment cleanup (#167), `check-upstream-version-task` structured multi-key state (#169) + CRLF state file (#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 closes#173 and #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`.

ptr727 · 2026-06-21T15:12:10Z

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 (Markdown convention: 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

build-docker-task hardcodes the image tag to SemVer2; wrapper repos need an external version #158 image tag is build-layer-owned; Clarify which parts of test-pull-request.yml are verbatim vs owned (unit-test job is .NET-coupled) #159 verbatim-vs-owned boundary in test-pull-request.yml; .editorconfig verbatim carry mixes line-ending governance with a large C#-only style block #160.editorconfig C# block marked .NET-only + first-time .gitattributes normalization; Brownfield re-sign: recommend filter-branch + committer rewrite, and clarify ruleset-blocking/ordering #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

Promote a Docker Hub README task (publish-docker-readme-task.yml) into the template #161publish-docker-readme-task.yml + Docker/README.md, wired into publish-release.yml.
Promote an upstream-dependency-version-tracker pattern into the template #157check-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.

Act on the issues surfaced porting ESPHome-NonRoot to the template, plus the comment/doc cleanup feedback. Docs: - Add a Comments house-rule (concise, current-state, no cross-project references, no rule citations, match ~120-col) and apply it. - Trim ~300 comment lines across .github/workflows/*; only comments changed (no logic), CRLF and SHA-pins preserved. - Resummarize copilot-instructions.md (drop duplicated PR-title block, historic narrative) keeping the Copilot runbook mechanics. - Bless trailing-backslash hard line breaks; clarify the cross-repo boundary (hub keeps the registry/fan-out rules, derived repos never name siblings); simplify the version.json rule; document HISTORY.md + CODESTYLE aggregate patterns. Workflows and CI: - Mark the .editorconfig C# block .NET-only; note first-time .gitattributes normalization. - Rewrite the brownfield re-sign procedure (filter-branch + committer rewrite, ruleset ordering, API verification, cleanup); clarify the maintainer-only force-push is restricted as a destructive operation, not a signing concern. - Ship publish-docker-readme-task.yml + Docker/README.md, wired into publish-release.yml. - Ship check-upstream-version-task.yml + merge-bot wiring for wrapper repos that track an upstream release. - Set retention-days: 1 on intermediate build artifacts and document the artifact-retention and registry-cache storage conventions. Add a Deferred Patterns backlog to the README.

Copilot

Pull request overview

This PR updates the ProjectTemplate documentation and GitHub Actions workflows to reflect lessons learned during downstream porting, focusing on clearer template/derived-repo boundaries, more concise current-state comments, and new reusable scaffolding for common downstream patterns.

Changes:

Refines core docs (AGENTS.md, README.md, copilot instructions) to add a comments house rule, clarify markdown hard-break conventions, and document derived-repo carry/ownership boundaries.
Trims and modernizes workflow comments across CI/release/codegen/merge-bot workflows without intended behavior changes, and documents CI artifact-retention/cache conventions.
Adds reusable workflows and docs for Docker Hub README publishing and upstream-version tracking (wrapper-repo pattern), plus wiring in publish/merge automation.

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
README.md	Adds a deferred-patterns section and clarifies derived-repo adoption guidance (incl. .gitattributes normalization).
DotNet.code-workspace	Updates workspace spellcheck/word allowlist.
Docker/README.md	Adds a Docker Hub repository overview README for the published image.
AGENTS.md	Adds comments house rules; clarifies test-pull-request ownership boundaries; documents artifact retention/cache guidance; adds wrapper-repo upstream-version tracker pattern.
.github/workflows/test-pull-request.yml	Trims/reshapes explanatory comments and clarifies unit-test job ownership for non-.NET repos.
.github/workflows/run-periodic-codegen-pull-request.yml	Trims schedule/concurrency commentary.
.github/workflows/run-codegen-pull-request-task.yml	Trims/modernizes comments; preserves codegen mechanics.
.github/workflows/publish-release.yml	Trims comments and wires in Docker Hub README publishing task.
.github/workflows/publish-docker-readme-task.yml	New reusable task to push Docker/README.md to Docker Hub.
.github/workflows/merge-bot-pull-request.yml	Adds auto-merge support for upstream-version bump PRs; trims header commentary.
.github/workflows/get-version-task.yml	Trims commentary around inputs/outputs and nbgv pin rationale.
.github/workflows/check-upstream-version-task.yml	New reusable task for wrapper repos to track upstream versions and open rolling bump PRs.
.github/workflows/build-release-task.yml	Trims and clarifies comments for orchestration/build seam and publishing invariants.
.github/workflows/build-pypilibrary-task.yml	Trims comments and sets short retention on build artifacts.
.github/workflows/build-nugetlibrary-task.yml	Trims comments and sets short retention on release-asset artifacts.
.github/workflows/build-executable-task.yml	Trims comments and sets short retention on intermediate/release artifacts.
.github/workflows/build-docker-task.yml	Trims comments (no intended logic changes) and clarifies cache/login rationale.
.github/copilot-instructions.md	Resummarizes/condenses the Copilot instructions while keeping the runbook mechanics.
.editorconfig	Marks the C# style block as .NET-only and clarifies the always-verbatim EOL governance block.

- Pin the docker-readme checkout to inputs.branch so the main leg always publishes main's readme regardless of the triggering ref. - Clarify that bump-branch-prefix must match the merge-bot's hard-coded upstream-version-<base> head refs or auto-merge won't fire. - Document that Docker immutable tags are NBGV SemVer2, including develop prerelease tags, not only X.Y.Z.

Copilot

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated 2 comments.

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>

… quota (#180) 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** (#178, closes#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** (#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** (#179): PR smoke builds no longer upload artifacts nothing consumes. - Plus prior develop work: docs/comment cleanup (#167), `check-upstream-version-task` structured multi-key state (#169) + CRLF state file (#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 closes#173 and #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`.

ptr727 · 2026-06-21T15:12:10Z

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 (Markdown convention: 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

build-docker-task hardcodes the image tag to SemVer2; wrapper repos need an external version #158 image tag is build-layer-owned; Clarify which parts of test-pull-request.yml are verbatim vs owned (unit-test job is .NET-coupled) #159 verbatim-vs-owned boundary in test-pull-request.yml; .editorconfig verbatim carry mixes line-ending governance with a large C#-only style block #160.editorconfig C# block marked .NET-only + first-time .gitattributes normalization; Brownfield re-sign: recommend filter-branch + committer rewrite, and clarify ruleset-blocking/ordering #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

Promote a Docker Hub README task (publish-docker-readme-task.yml) into the template #161publish-docker-readme-task.yml + Docker/README.md, wired into publish-release.yml.
Promote an upstream-dependency-version-tracker pattern into the template #157check-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.

Act on the issues surfaced porting ESPHome-NonRoot to the template, plus the comment/doc cleanup feedback. Docs: - Add a Comments house-rule (concise, current-state, no cross-project references, no rule citations, match ~120-col) and apply it. - Trim ~300 comment lines across .github/workflows/*; only comments changed (no logic), CRLF and SHA-pins preserved. - Resummarize copilot-instructions.md (drop duplicated PR-title block, historic narrative) keeping the Copilot runbook mechanics. - Bless trailing-backslash hard line breaks; clarify the cross-repo boundary (hub keeps the registry/fan-out rules, derived repos never name siblings); simplify the version.json rule; document HISTORY.md + CODESTYLE aggregate patterns. Workflows and CI: - Mark the .editorconfig C# block .NET-only; note first-time .gitattributes normalization. - Rewrite the brownfield re-sign procedure (filter-branch + committer rewrite, ruleset ordering, API verification, cleanup); clarify the maintainer-only force-push is restricted as a destructive operation, not a signing concern. - Ship publish-docker-readme-task.yml + Docker/README.md, wired into publish-release.yml. - Ship check-upstream-version-task.yml + merge-bot wiring for wrapper repos that track an upstream release. - Set retention-days: 1 on intermediate build artifacts and document the artifact-retention and registry-cache storage conventions. Add a Deferred Patterns backlog to the README.

Copilot

Pull request overview

This PR updates the ProjectTemplate documentation and GitHub Actions workflows to reflect lessons learned during downstream porting, focusing on clearer template/derived-repo boundaries, more concise current-state comments, and new reusable scaffolding for common downstream patterns.

Changes:

Refines core docs (AGENTS.md, README.md, copilot instructions) to add a comments house rule, clarify markdown hard-break conventions, and document derived-repo carry/ownership boundaries.
Trims and modernizes workflow comments across CI/release/codegen/merge-bot workflows without intended behavior changes, and documents CI artifact-retention/cache conventions.
Adds reusable workflows and docs for Docker Hub README publishing and upstream-version tracking (wrapper-repo pattern), plus wiring in publish/merge automation.

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
README.md	Adds a deferred-patterns section and clarifies derived-repo adoption guidance (incl. .gitattributes normalization).
DotNet.code-workspace	Updates workspace spellcheck/word allowlist.
Docker/README.md	Adds a Docker Hub repository overview README for the published image.
AGENTS.md	Adds comments house rules; clarifies test-pull-request ownership boundaries; documents artifact retention/cache guidance; adds wrapper-repo upstream-version tracker pattern.
.github/workflows/test-pull-request.yml	Trims/reshapes explanatory comments and clarifies unit-test job ownership for non-.NET repos.
.github/workflows/run-periodic-codegen-pull-request.yml	Trims schedule/concurrency commentary.
.github/workflows/run-codegen-pull-request-task.yml	Trims/modernizes comments; preserves codegen mechanics.
.github/workflows/publish-release.yml	Trims comments and wires in Docker Hub README publishing task.
.github/workflows/publish-docker-readme-task.yml	New reusable task to push Docker/README.md to Docker Hub.
.github/workflows/merge-bot-pull-request.yml	Adds auto-merge support for upstream-version bump PRs; trims header commentary.
.github/workflows/get-version-task.yml	Trims commentary around inputs/outputs and nbgv pin rationale.
.github/workflows/check-upstream-version-task.yml	New reusable task for wrapper repos to track upstream versions and open rolling bump PRs.
.github/workflows/build-release-task.yml	Trims and clarifies comments for orchestration/build seam and publishing invariants.
.github/workflows/build-pypilibrary-task.yml	Trims comments and sets short retention on build artifacts.
.github/workflows/build-nugetlibrary-task.yml	Trims comments and sets short retention on release-asset artifacts.
.github/workflows/build-executable-task.yml	Trims comments and sets short retention on intermediate/release artifacts.
.github/workflows/build-docker-task.yml	Trims comments (no intended logic changes) and clarifies cache/login rationale.
.github/copilot-instructions.md	Resummarizes/condenses the Copilot instructions while keeping the runbook mechanics.
.editorconfig	Marks the C# style block as .NET-only and clarifies the always-verbatim EOL governance block.

- Pin the docker-readme checkout to inputs.branch so the main leg always publishes main's readme regardless of the triggering ref. - Clarify that bump-branch-prefix must match the merge-bot's hard-coded upstream-version-<base> head refs or auto-merge won't fire. - Document that Docker immutable tags are NBGV SemVer2, including develop prerelease tags, not only X.Y.Z.

Copilot

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated 2 comments.

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>

… quota (#180) 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** (#178, closes#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** (#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** (#179): PR smoke builds no longer upload artifacts nothing consumes. - Plus prior develop work: docs/comment cleanup (#167), `check-upstream-version-task` structured multi-key state (#169) + CRLF state file (#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 closes#173 and #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`.

ptr727 · 2026-06-21T15:12:10Z

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 (Markdown convention: 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

build-docker-task hardcodes the image tag to SemVer2; wrapper repos need an external version #158 image tag is build-layer-owned; Clarify which parts of test-pull-request.yml are verbatim vs owned (unit-test job is .NET-coupled) #159 verbatim-vs-owned boundary in test-pull-request.yml; .editorconfig verbatim carry mixes line-ending governance with a large C#-only style block #160.editorconfig C# block marked .NET-only + first-time .gitattributes normalization; Brownfield re-sign: recommend filter-branch + committer rewrite, and clarify ruleset-blocking/ordering #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

Promote a Docker Hub README task (publish-docker-readme-task.yml) into the template #161publish-docker-readme-task.yml + Docker/README.md, wired into publish-release.yml.
Promote an upstream-dependency-version-tracker pattern into the template #157check-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.

Act on the issues surfaced porting ESPHome-NonRoot to the template, plus the comment/doc cleanup feedback. Docs: - Add a Comments house-rule (concise, current-state, no cross-project references, no rule citations, match ~120-col) and apply it. - Trim ~300 comment lines across .github/workflows/*; only comments changed (no logic), CRLF and SHA-pins preserved. - Resummarize copilot-instructions.md (drop duplicated PR-title block, historic narrative) keeping the Copilot runbook mechanics. - Bless trailing-backslash hard line breaks; clarify the cross-repo boundary (hub keeps the registry/fan-out rules, derived repos never name siblings); simplify the version.json rule; document HISTORY.md + CODESTYLE aggregate patterns. Workflows and CI: - Mark the .editorconfig C# block .NET-only; note first-time .gitattributes normalization. - Rewrite the brownfield re-sign procedure (filter-branch + committer rewrite, ruleset ordering, API verification, cleanup); clarify the maintainer-only force-push is restricted as a destructive operation, not a signing concern. - Ship publish-docker-readme-task.yml + Docker/README.md, wired into publish-release.yml. - Ship check-upstream-version-task.yml + merge-bot wiring for wrapper repos that track an upstream release. - Set retention-days: 1 on intermediate build artifacts and document the artifact-retention and registry-cache storage conventions. Add a Deferred Patterns backlog to the README.

Copilot

Pull request overview

This PR updates the ProjectTemplate documentation and GitHub Actions workflows to reflect lessons learned during downstream porting, focusing on clearer template/derived-repo boundaries, more concise current-state comments, and new reusable scaffolding for common downstream patterns.

Changes:

Refines core docs (AGENTS.md, README.md, copilot instructions) to add a comments house rule, clarify markdown hard-break conventions, and document derived-repo carry/ownership boundaries.
Trims and modernizes workflow comments across CI/release/codegen/merge-bot workflows without intended behavior changes, and documents CI artifact-retention/cache conventions.
Adds reusable workflows and docs for Docker Hub README publishing and upstream-version tracking (wrapper-repo pattern), plus wiring in publish/merge automation.

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
README.md	Adds a deferred-patterns section and clarifies derived-repo adoption guidance (incl. .gitattributes normalization).
DotNet.code-workspace	Updates workspace spellcheck/word allowlist.
Docker/README.md	Adds a Docker Hub repository overview README for the published image.
AGENTS.md	Adds comments house rules; clarifies test-pull-request ownership boundaries; documents artifact retention/cache guidance; adds wrapper-repo upstream-version tracker pattern.
.github/workflows/test-pull-request.yml	Trims/reshapes explanatory comments and clarifies unit-test job ownership for non-.NET repos.
.github/workflows/run-periodic-codegen-pull-request.yml	Trims schedule/concurrency commentary.
.github/workflows/run-codegen-pull-request-task.yml	Trims/modernizes comments; preserves codegen mechanics.
.github/workflows/publish-release.yml	Trims comments and wires in Docker Hub README publishing task.
.github/workflows/publish-docker-readme-task.yml	New reusable task to push Docker/README.md to Docker Hub.
.github/workflows/merge-bot-pull-request.yml	Adds auto-merge support for upstream-version bump PRs; trims header commentary.
.github/workflows/get-version-task.yml	Trims commentary around inputs/outputs and nbgv pin rationale.
.github/workflows/check-upstream-version-task.yml	New reusable task for wrapper repos to track upstream versions and open rolling bump PRs.
.github/workflows/build-release-task.yml	Trims and clarifies comments for orchestration/build seam and publishing invariants.
.github/workflows/build-pypilibrary-task.yml	Trims comments and sets short retention on build artifacts.
.github/workflows/build-nugetlibrary-task.yml	Trims comments and sets short retention on release-asset artifacts.
.github/workflows/build-executable-task.yml	Trims comments and sets short retention on intermediate/release artifacts.
.github/workflows/build-docker-task.yml	Trims comments (no intended logic changes) and clarifies cache/login rationale.
.github/copilot-instructions.md	Resummarizes/condenses the Copilot instructions while keeping the runbook mechanics.
.editorconfig	Marks the C# style block as .NET-only and clarifies the always-verbatim EOL governance block.

- Pin the docker-readme checkout to inputs.branch so the main leg always publishes main's readme regardless of the triggering ref. - Clarify that bump-branch-prefix must match the merge-bot's hard-coded upstream-version-<base> head refs or auto-merge won't fire. - Document that Docker immutable tags are NBGV SemVer2, including develop prerelease tags, not only X.Y.Z.

Copilot

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated 2 comments.

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>

… quota (#180) 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** (#178, closes#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** (#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** (#179): PR smoke builds no longer upload artifacts nothing consumes. - Plus prior develop work: docs/comment cleanup (#167), `check-upstream-version-task` structured multi-key state (#169) + CRLF state file (#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 closes#173 and #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`.

ptr727 · 2026-06-21T15:12:10Z

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 (Markdown convention: 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

build-docker-task hardcodes the image tag to SemVer2; wrapper repos need an external version #158 image tag is build-layer-owned; Clarify which parts of test-pull-request.yml are verbatim vs owned (unit-test job is .NET-coupled) #159 verbatim-vs-owned boundary in test-pull-request.yml; .editorconfig verbatim carry mixes line-ending governance with a large C#-only style block #160.editorconfig C# block marked .NET-only + first-time .gitattributes normalization; Brownfield re-sign: recommend filter-branch + committer rewrite, and clarify ruleset-blocking/ordering #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

Promote a Docker Hub README task (publish-docker-readme-task.yml) into the template #161publish-docker-readme-task.yml + Docker/README.md, wired into publish-release.yml.
Promote an upstream-dependency-version-tracker pattern into the template #157check-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.

Act on the issues surfaced porting ESPHome-NonRoot to the template, plus the comment/doc cleanup feedback. Docs: - Add a Comments house-rule (concise, current-state, no cross-project references, no rule citations, match ~120-col) and apply it. - Trim ~300 comment lines across .github/workflows/*; only comments changed (no logic), CRLF and SHA-pins preserved. - Resummarize copilot-instructions.md (drop duplicated PR-title block, historic narrative) keeping the Copilot runbook mechanics. - Bless trailing-backslash hard line breaks; clarify the cross-repo boundary (hub keeps the registry/fan-out rules, derived repos never name siblings); simplify the version.json rule; document HISTORY.md + CODESTYLE aggregate patterns. Workflows and CI: - Mark the .editorconfig C# block .NET-only; note first-time .gitattributes normalization. - Rewrite the brownfield re-sign procedure (filter-branch + committer rewrite, ruleset ordering, API verification, cleanup); clarify the maintainer-only force-push is restricted as a destructive operation, not a signing concern. - Ship publish-docker-readme-task.yml + Docker/README.md, wired into publish-release.yml. - Ship check-upstream-version-task.yml + merge-bot wiring for wrapper repos that track an upstream release. - Set retention-days: 1 on intermediate build artifacts and document the artifact-retention and registry-cache storage conventions. Add a Deferred Patterns backlog to the README.

Copilot

Pull request overview

This PR updates the ProjectTemplate documentation and GitHub Actions workflows to reflect lessons learned during downstream porting, focusing on clearer template/derived-repo boundaries, more concise current-state comments, and new reusable scaffolding for common downstream patterns.

Changes:

Refines core docs (AGENTS.md, README.md, copilot instructions) to add a comments house rule, clarify markdown hard-break conventions, and document derived-repo carry/ownership boundaries.
Trims and modernizes workflow comments across CI/release/codegen/merge-bot workflows without intended behavior changes, and documents CI artifact-retention/cache conventions.
Adds reusable workflows and docs for Docker Hub README publishing and upstream-version tracking (wrapper-repo pattern), plus wiring in publish/merge automation.

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
README.md	Adds a deferred-patterns section and clarifies derived-repo adoption guidance (incl. .gitattributes normalization).
DotNet.code-workspace	Updates workspace spellcheck/word allowlist.
Docker/README.md	Adds a Docker Hub repository overview README for the published image.
AGENTS.md	Adds comments house rules; clarifies test-pull-request ownership boundaries; documents artifact retention/cache guidance; adds wrapper-repo upstream-version tracker pattern.
.github/workflows/test-pull-request.yml	Trims/reshapes explanatory comments and clarifies unit-test job ownership for non-.NET repos.
.github/workflows/run-periodic-codegen-pull-request.yml	Trims schedule/concurrency commentary.
.github/workflows/run-codegen-pull-request-task.yml	Trims/modernizes comments; preserves codegen mechanics.
.github/workflows/publish-release.yml	Trims comments and wires in Docker Hub README publishing task.
.github/workflows/publish-docker-readme-task.yml	New reusable task to push Docker/README.md to Docker Hub.
.github/workflows/merge-bot-pull-request.yml	Adds auto-merge support for upstream-version bump PRs; trims header commentary.
.github/workflows/get-version-task.yml	Trims commentary around inputs/outputs and nbgv pin rationale.
.github/workflows/check-upstream-version-task.yml	New reusable task for wrapper repos to track upstream versions and open rolling bump PRs.
.github/workflows/build-release-task.yml	Trims and clarifies comments for orchestration/build seam and publishing invariants.
.github/workflows/build-pypilibrary-task.yml	Trims comments and sets short retention on build artifacts.
.github/workflows/build-nugetlibrary-task.yml	Trims comments and sets short retention on release-asset artifacts.
.github/workflows/build-executable-task.yml	Trims comments and sets short retention on intermediate/release artifacts.
.github/workflows/build-docker-task.yml	Trims comments (no intended logic changes) and clarifies cache/login rationale.
.github/copilot-instructions.md	Resummarizes/condenses the Copilot instructions while keeping the runbook mechanics.
.editorconfig	Marks the C# style block as .NET-only and clarifies the always-verbatim EOL governance block.

- Pin the docker-readme checkout to inputs.branch so the main leg always publishes main's readme regardless of the triggering ref. - Clarify that bump-branch-prefix must match the merge-bot's hard-coded upstream-version-<base> head refs or auto-merge won't fire. - Document that Docker immutable tags are NBGV SemVer2, including develop prerelease tags, not only X.Y.Z.

Copilot

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated 2 comments.

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>

… quota (#180) 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** (#178, closes#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** (#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** (#179): PR smoke builds no longer upload artifacts nothing consumes. - Plus prior develop work: docs/comment cleanup (#167), `check-upstream-version-task` structured multi-key state (#169) + CRLF state file (#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 closes#173 and #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`.

ptr727 · 2026-06-21T15:12:10Z

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 (Markdown convention: 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

build-docker-task hardcodes the image tag to SemVer2; wrapper repos need an external version #158 image tag is build-layer-owned; Clarify which parts of test-pull-request.yml are verbatim vs owned (unit-test job is .NET-coupled) #159 verbatim-vs-owned boundary in test-pull-request.yml; .editorconfig verbatim carry mixes line-ending governance with a large C#-only style block #160.editorconfig C# block marked .NET-only + first-time .gitattributes normalization; Brownfield re-sign: recommend filter-branch + committer rewrite, and clarify ruleset-blocking/ordering #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

Promote a Docker Hub README task (publish-docker-readme-task.yml) into the template #161publish-docker-readme-task.yml + Docker/README.md, wired into publish-release.yml.
Promote an upstream-dependency-version-tracker pattern into the template #157check-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.

Act on the issues surfaced porting ESPHome-NonRoot to the template, plus the comment/doc cleanup feedback. Docs: - Add a Comments house-rule (concise, current-state, no cross-project references, no rule citations, match ~120-col) and apply it. - Trim ~300 comment lines across .github/workflows/*; only comments changed (no logic), CRLF and SHA-pins preserved. - Resummarize copilot-instructions.md (drop duplicated PR-title block, historic narrative) keeping the Copilot runbook mechanics. - Bless trailing-backslash hard line breaks; clarify the cross-repo boundary (hub keeps the registry/fan-out rules, derived repos never name siblings); simplify the version.json rule; document HISTORY.md + CODESTYLE aggregate patterns. Workflows and CI: - Mark the .editorconfig C# block .NET-only; note first-time .gitattributes normalization. - Rewrite the brownfield re-sign procedure (filter-branch + committer rewrite, ruleset ordering, API verification, cleanup); clarify the maintainer-only force-push is restricted as a destructive operation, not a signing concern. - Ship publish-docker-readme-task.yml + Docker/README.md, wired into publish-release.yml. - Ship check-upstream-version-task.yml + merge-bot wiring for wrapper repos that track an upstream release. - Set retention-days: 1 on intermediate build artifacts and document the artifact-retention and registry-cache storage conventions. Add a Deferred Patterns backlog to the README.

Copilot

Pull request overview

This PR updates the ProjectTemplate documentation and GitHub Actions workflows to reflect lessons learned during downstream porting, focusing on clearer template/derived-repo boundaries, more concise current-state comments, and new reusable scaffolding for common downstream patterns.

Changes:

Refines core docs (AGENTS.md, README.md, copilot instructions) to add a comments house rule, clarify markdown hard-break conventions, and document derived-repo carry/ownership boundaries.
Trims and modernizes workflow comments across CI/release/codegen/merge-bot workflows without intended behavior changes, and documents CI artifact-retention/cache conventions.
Adds reusable workflows and docs for Docker Hub README publishing and upstream-version tracking (wrapper-repo pattern), plus wiring in publish/merge automation.

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
README.md	Adds a deferred-patterns section and clarifies derived-repo adoption guidance (incl. .gitattributes normalization).
DotNet.code-workspace	Updates workspace spellcheck/word allowlist.
Docker/README.md	Adds a Docker Hub repository overview README for the published image.
AGENTS.md	Adds comments house rules; clarifies test-pull-request ownership boundaries; documents artifact retention/cache guidance; adds wrapper-repo upstream-version tracker pattern.
.github/workflows/test-pull-request.yml	Trims/reshapes explanatory comments and clarifies unit-test job ownership for non-.NET repos.
.github/workflows/run-periodic-codegen-pull-request.yml	Trims schedule/concurrency commentary.
.github/workflows/run-codegen-pull-request-task.yml	Trims/modernizes comments; preserves codegen mechanics.
.github/workflows/publish-release.yml	Trims comments and wires in Docker Hub README publishing task.
.github/workflows/publish-docker-readme-task.yml	New reusable task to push Docker/README.md to Docker Hub.
.github/workflows/merge-bot-pull-request.yml	Adds auto-merge support for upstream-version bump PRs; trims header commentary.
.github/workflows/get-version-task.yml	Trims commentary around inputs/outputs and nbgv pin rationale.
.github/workflows/check-upstream-version-task.yml	New reusable task for wrapper repos to track upstream versions and open rolling bump PRs.
.github/workflows/build-release-task.yml	Trims and clarifies comments for orchestration/build seam and publishing invariants.
.github/workflows/build-pypilibrary-task.yml	Trims comments and sets short retention on build artifacts.
.github/workflows/build-nugetlibrary-task.yml	Trims comments and sets short retention on release-asset artifacts.
.github/workflows/build-executable-task.yml	Trims comments and sets short retention on intermediate/release artifacts.
.github/workflows/build-docker-task.yml	Trims comments (no intended logic changes) and clarifies cache/login rationale.
.github/copilot-instructions.md	Resummarizes/condenses the Copilot instructions while keeping the runbook mechanics.
.editorconfig	Marks the C# style block as .NET-only and clarifies the always-verbatim EOL governance block.

- Pin the docker-readme checkout to inputs.branch so the main leg always publishes main's readme regardless of the triggering ref. - Clarify that bump-branch-prefix must match the merge-bot's hard-coded upstream-version-<base> head refs or auto-merge won't fire. - Document that Docker immutable tags are NBGV SemVer2, including develop prerelease tags, not only X.Y.Z.

Copilot

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated 2 comments.

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>

… quota (#180) 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** (#178, closes#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** (#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** (#179): PR smoke builds no longer upload artifacts nothing consumes. - Plus prior develop work: docs/comment cleanup (#167), `check-upstream-version-task` structured multi-key state (#169) + CRLF state file (#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 closes#173 and #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`.

ptr727 · 2026-06-21T15:12:10Z

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 (Markdown convention: 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

build-docker-task hardcodes the image tag to SemVer2; wrapper repos need an external version #158 image tag is build-layer-owned; Clarify which parts of test-pull-request.yml are verbatim vs owned (unit-test job is .NET-coupled) #159 verbatim-vs-owned boundary in test-pull-request.yml; .editorconfig verbatim carry mixes line-ending governance with a large C#-only style block #160.editorconfig C# block marked .NET-only + first-time .gitattributes normalization; Brownfield re-sign: recommend filter-branch + committer rewrite, and clarify ruleset-blocking/ordering #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

Promote a Docker Hub README task (publish-docker-readme-task.yml) into the template #161publish-docker-readme-task.yml + Docker/README.md, wired into publish-release.yml.
Promote an upstream-dependency-version-tracker pattern into the template #157check-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.

Act on the issues surfaced porting ESPHome-NonRoot to the template, plus the comment/doc cleanup feedback. Docs: - Add a Comments house-rule (concise, current-state, no cross-project references, no rule citations, match ~120-col) and apply it. - Trim ~300 comment lines across .github/workflows/*; only comments changed (no logic), CRLF and SHA-pins preserved. - Resummarize copilot-instructions.md (drop duplicated PR-title block, historic narrative) keeping the Copilot runbook mechanics. - Bless trailing-backslash hard line breaks; clarify the cross-repo boundary (hub keeps the registry/fan-out rules, derived repos never name siblings); simplify the version.json rule; document HISTORY.md + CODESTYLE aggregate patterns. Workflows and CI: - Mark the .editorconfig C# block .NET-only; note first-time .gitattributes normalization. - Rewrite the brownfield re-sign procedure (filter-branch + committer rewrite, ruleset ordering, API verification, cleanup); clarify the maintainer-only force-push is restricted as a destructive operation, not a signing concern. - Ship publish-docker-readme-task.yml + Docker/README.md, wired into publish-release.yml. - Ship check-upstream-version-task.yml + merge-bot wiring for wrapper repos that track an upstream release. - Set retention-days: 1 on intermediate build artifacts and document the artifact-retention and registry-cache storage conventions. Add a Deferred Patterns backlog to the README.

Copilot

Pull request overview

This PR updates the ProjectTemplate documentation and GitHub Actions workflows to reflect lessons learned during downstream porting, focusing on clearer template/derived-repo boundaries, more concise current-state comments, and new reusable scaffolding for common downstream patterns.

Changes:

Refines core docs (AGENTS.md, README.md, copilot instructions) to add a comments house rule, clarify markdown hard-break conventions, and document derived-repo carry/ownership boundaries.
Trims and modernizes workflow comments across CI/release/codegen/merge-bot workflows without intended behavior changes, and documents CI artifact-retention/cache conventions.
Adds reusable workflows and docs for Docker Hub README publishing and upstream-version tracking (wrapper-repo pattern), plus wiring in publish/merge automation.

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
README.md	Adds a deferred-patterns section and clarifies derived-repo adoption guidance (incl. .gitattributes normalization).
DotNet.code-workspace	Updates workspace spellcheck/word allowlist.
Docker/README.md	Adds a Docker Hub repository overview README for the published image.
AGENTS.md	Adds comments house rules; clarifies test-pull-request ownership boundaries; documents artifact retention/cache guidance; adds wrapper-repo upstream-version tracker pattern.
.github/workflows/test-pull-request.yml	Trims/reshapes explanatory comments and clarifies unit-test job ownership for non-.NET repos.
.github/workflows/run-periodic-codegen-pull-request.yml	Trims schedule/concurrency commentary.
.github/workflows/run-codegen-pull-request-task.yml	Trims/modernizes comments; preserves codegen mechanics.
.github/workflows/publish-release.yml	Trims comments and wires in Docker Hub README publishing task.
.github/workflows/publish-docker-readme-task.yml	New reusable task to push Docker/README.md to Docker Hub.
.github/workflows/merge-bot-pull-request.yml	Adds auto-merge support for upstream-version bump PRs; trims header commentary.
.github/workflows/get-version-task.yml	Trims commentary around inputs/outputs and nbgv pin rationale.
.github/workflows/check-upstream-version-task.yml	New reusable task for wrapper repos to track upstream versions and open rolling bump PRs.
.github/workflows/build-release-task.yml	Trims and clarifies comments for orchestration/build seam and publishing invariants.
.github/workflows/build-pypilibrary-task.yml	Trims comments and sets short retention on build artifacts.
.github/workflows/build-nugetlibrary-task.yml	Trims comments and sets short retention on release-asset artifacts.
.github/workflows/build-executable-task.yml	Trims comments and sets short retention on intermediate/release artifacts.
.github/workflows/build-docker-task.yml	Trims comments (no intended logic changes) and clarifies cache/login rationale.
.github/copilot-instructions.md	Resummarizes/condenses the Copilot instructions while keeping the runbook mechanics.
.editorconfig	Marks the C# style block as .NET-only and clarifies the always-verbatim EOL governance block.

- Pin the docker-readme checkout to inputs.branch so the main leg always publishes main's readme regardless of the triggering ref. - Clarify that bump-branch-prefix must match the merge-bot's hard-coded upstream-version-<base> head refs or auto-merge won't fire. - Document that Docker immutable tags are NBGV SemVer2, including develop prerelease tags, not only X.Y.Z.

Copilot

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated 2 comments.

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>

… quota (#180) 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** (#178, closes#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** (#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** (#179): PR smoke builds no longer upload artifacts nothing consumes. - Plus prior develop work: docs/comment cleanup (#167), `check-upstream-version-task` structured multi-key state (#169) + CRLF state file (#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 closes#173 and #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`.

CopilotAI review requested due to automatic review settings June 21, 2026 15:12

Copilotstarted reviewing on behalf of ptr727 June 21, 2026 15:12 View session

CopilotAI reviewed Jun 21, 2026
View reviewed changes

Comment thread.github/workflows/publish-docker-readme-task.yml
Comment thread.github/workflows/check-upstream-version-task.yml
Comment threadDocker/README.md Outdated
Comment thread.github/workflows/get-version-task.yml

ptr727 requested a review from Copilot June 21, 2026 15:19

Copilotstarted reviewing on behalf of ptr727 June 21, 2026 15:20 View session

CopilotAI reviewed Jun 21, 2026
View reviewed changes

Comment thread.github/workflows/check-upstream-version-task.yml
Comment thread.github/workflows/publish-docker-readme-task.yml

ptr727 merged commit 212d8a8 into developJun 21, 2026
15 checks passed

ptr727 deleted the template-cleanup-porting-issues branch June 21, 2026 16:52

ptr727 mentioned this pull request Jun 22, 2026
Promote develop to main: CODESTYLE consolidation, Copilot runbook, CI quota #180
Merged

CopilotAI review requested due to automatic review settings June 21, 2026 15:12

Copilotstarted reviewing on behalf of ptr727 June 21, 2026 15:12 View session

CopilotAI reviewed Jun 21, 2026
View reviewed changes

Comment thread.github/workflows/publish-docker-readme-task.yml
Comment thread.github/workflows/check-upstream-version-task.yml
Comment threadDocker/README.md Outdated
Comment thread.github/workflows/get-version-task.yml

ptr727 requested a review from Copilot June 21, 2026 15:19

Copilotstarted reviewing on behalf of ptr727 June 21, 2026 15:20 View session

CopilotAI reviewed Jun 21, 2026
View reviewed changes

Comment thread.github/workflows/check-upstream-version-task.yml
Comment thread.github/workflows/publish-docker-readme-task.yml

ptr727 merged commit 212d8a8 into developJun 21, 2026
15 checks passed

ptr727 deleted the template-cleanup-porting-issues branch June 21, 2026 16:52

ptr727 mentioned this pull request Jun 22, 2026
Promote develop to main: CODESTYLE consolidation, Copilot runbook, CI quota #180
Merged

CopilotAI review requested due to automatic review settings June 21, 2026 15:12

Copilotstarted reviewing on behalf of ptr727 June 21, 2026 15:12 View session

CopilotAI reviewed Jun 21, 2026
View reviewed changes

Comment thread.github/workflows/publish-docker-readme-task.yml
Comment thread.github/workflows/check-upstream-version-task.yml
Comment threadDocker/README.md Outdated
Comment thread.github/workflows/get-version-task.yml

ptr727 requested a review from Copilot June 21, 2026 15:19

Copilotstarted reviewing on behalf of ptr727 June 21, 2026 15:20 View session

CopilotAI reviewed Jun 21, 2026
View reviewed changes

Comment thread.github/workflows/check-upstream-version-task.yml
Comment thread.github/workflows/publish-docker-readme-task.yml

ptr727 merged commit 212d8a8 into developJun 21, 2026
15 checks passed

ptr727 deleted the template-cleanup-porting-issues branch June 21, 2026 16:52

ptr727 mentioned this pull request Jun 22, 2026
Promote develop to main: CODESTYLE consolidation, Copilot runbook, CI quota #180
Merged

CopilotAI review requested due to automatic review settings June 21, 2026 15:12

Copilotstarted reviewing on behalf of ptr727 June 21, 2026 15:12 View session

CopilotAI reviewed Jun 21, 2026
View reviewed changes

Comment thread.github/workflows/publish-docker-readme-task.yml
Comment thread.github/workflows/check-upstream-version-task.yml
Comment threadDocker/README.md Outdated
Comment thread.github/workflows/get-version-task.yml

ptr727 requested a review from Copilot June 21, 2026 15:19

Copilotstarted reviewing on behalf of ptr727 June 21, 2026 15:20 View session

CopilotAI reviewed Jun 21, 2026
View reviewed changes

Comment thread.github/workflows/check-upstream-version-task.yml
Comment thread.github/workflows/publish-docker-readme-task.yml

ptr727 merged commit 212d8a8 into developJun 21, 2026
15 checks passed

ptr727 deleted the template-cleanup-porting-issues branch June 21, 2026 16:52

ptr727 mentioned this pull request Jun 22, 2026
Promote develop to main: CODESTYLE consolidation, Copilot runbook, CI quota #180
Merged

CopilotAI review requested due to automatic review settings June 21, 2026 15:12

Copilotstarted reviewing on behalf of ptr727 June 21, 2026 15:12 View session

CopilotAI reviewed Jun 21, 2026
View reviewed changes

Comment thread.github/workflows/publish-docker-readme-task.yml
Comment thread.github/workflows/check-upstream-version-task.yml
Comment threadDocker/README.md Outdated
Comment thread.github/workflows/get-version-task.yml

ptr727 requested a review from Copilot June 21, 2026 15:19

Copilotstarted reviewing on behalf of ptr727 June 21, 2026 15:20 View session

CopilotAI reviewed Jun 21, 2026
View reviewed changes

Comment thread.github/workflows/check-upstream-version-task.yml
Comment thread.github/workflows/publish-docker-readme-task.yml

ptr727 merged commit 212d8a8 into developJun 21, 2026
15 checks passed

ptr727 deleted the template-cleanup-porting-issues branch June 21, 2026 16:52

ptr727 mentioned this pull request Jun 22, 2026
Promote develop to main: CODESTYLE consolidation, Copilot runbook, CI quota #180
Merged

CopilotAI review requested due to automatic review settings June 21, 2026 15:12

Copilotstarted reviewing on behalf of ptr727 June 21, 2026 15:12 View session

CopilotAI reviewed Jun 21, 2026
View reviewed changes

Comment thread.github/workflows/publish-docker-readme-task.yml
Comment thread.github/workflows/check-upstream-version-task.yml
Comment threadDocker/README.md Outdated
Comment thread.github/workflows/get-version-task.yml

ptr727 requested a review from Copilot June 21, 2026 15:19

Copilotstarted reviewing on behalf of ptr727 June 21, 2026 15:20 View session

CopilotAI reviewed Jun 21, 2026
View reviewed changes

Comment thread.github/workflows/check-upstream-version-task.yml
Comment thread.github/workflows/publish-docker-readme-task.yml

ptr727 merged commit 212d8a8 into developJun 21, 2026
15 checks passed

ptr727 deleted the template-cleanup-porting-issues branch June 21, 2026 16:52

ptr727 mentioned this pull request Jun 22, 2026
Promote develop to main: CODESTYLE consolidation, Copilot runbook, CI quota #180
Merged

CopilotAI review requested due to automatic review settings June 21, 2026 15:12

Copilotstarted reviewing on behalf of ptr727 June 21, 2026 15:12 View session

CopilotAI reviewed Jun 21, 2026
View reviewed changes

Comment thread.github/workflows/publish-docker-readme-task.yml
Comment thread.github/workflows/check-upstream-version-task.yml
Comment threadDocker/README.md Outdated
Comment thread.github/workflows/get-version-task.yml

ptr727 requested a review from Copilot June 21, 2026 15:19

Copilotstarted reviewing on behalf of ptr727 June 21, 2026 15:20 View session

CopilotAI reviewed Jun 21, 2026
View reviewed changes

Comment thread.github/workflows/check-upstream-version-task.yml
Comment thread.github/workflows/publish-docker-readme-task.yml

ptr727 merged commit 212d8a8 into developJun 21, 2026
15 checks passed

ptr727 deleted the template-cleanup-porting-issues branch June 21, 2026 16:52

ptr727 mentioned this pull request Jun 22, 2026
Promote develop to main: CODESTYLE consolidation, Copilot runbook, CI quota #180
Merged

CopilotAI review requested due to automatic review settings June 21, 2026 15:12

Copilotstarted reviewing on behalf of ptr727 June 21, 2026 15:12 View session

CopilotAI reviewed Jun 21, 2026
View reviewed changes

Comment thread.github/workflows/publish-docker-readme-task.yml
Comment thread.github/workflows/check-upstream-version-task.yml
Comment threadDocker/README.md Outdated
Comment thread.github/workflows/get-version-task.yml

ptr727 requested a review from Copilot June 21, 2026 15:19

Copilotstarted reviewing on behalf of ptr727 June 21, 2026 15:20 View session

CopilotAI reviewed Jun 21, 2026
View reviewed changes

Comment thread.github/workflows/check-upstream-version-task.yml
Comment thread.github/workflows/publish-docker-readme-task.yml

ptr727 merged commit 212d8a8 into developJun 21, 2026
15 checks passed

ptr727 deleted the template-cleanup-porting-issues branch June 21, 2026 16:52

ptr727 mentioned this pull request Jun 22, 2026
Promote develop to main: CODESTYLE consolidation, Copilot runbook, CI quota #180
Merged

Conversation

ptr727 commented Jun 21, 2026

Docs

Workflow comments (#162)

Doc-clarification issues

New reusable tasks

CI storage

README

Uh oh!

CopilotAI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

CopilotAI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

ptr727 commented Jun 21, 2026

Docs

Workflow comments (#162)

Doc-clarification issues

New reusable tasks

CI storage

README

Uh oh!

CopilotAI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

CopilotAI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

ptr727 commented Jun 21, 2026

Docs

Workflow comments (#162)

Doc-clarification issues

New reusable tasks

CI storage

README

Uh oh!

CopilotAI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!