Resummarize template docs and trim workflow comments - #167
Merged
Conversation
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.
Contributor
There was a problem hiding this comment.
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.
This was referenced Jun 21, 2026
Closed
Closed
Closed
Closed
ptr727
added a commit
that referenced
this pull request
Jun 21, 2026
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>
ptr727
added a commit
that referenced
this pull request
Jun 22, 2026
… 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`.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Acts on the issues surfaced while porting ESPHome-NonRoot to the template (#157-#164), plus the comment/doc cleanup and CI-storage feedback.
Docs
version.jsonbump rule; document the HISTORY.md + README release-notes and CODESTYLE-aggregate patterns.Workflow comments (#162)
.github/workflows/*. Only comments changed (no logic), CRLF endings and action SHA-pins preserved.Doc-clarification issues
test-pull-request.yml; .editorconfig verbatim carry mixes line-ending governance with a large C#-only style block #160.editorconfigC# block marked .NET-only + first-time.gitattributesnormalization; 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
publish-docker-readme-task.yml+Docker/README.md, wired intopublish-release.yml.check-upstream-version-task.yml+merge-upstream-versionwiring for wrapper repos that track an upstream release; state file standardized at the repo root.CI storage
retention-days: 1on all intermediate build artifacts (was 90-day default); documented the artifact-retention and registry-cache (type=registry, nottype=gha) conventions.README
Verified: actionlint clean, markdownlint clean, all touched
.yml/.mdCRLF, all actions SHA-pinned.