Skip to content

Promote develop to main: CODESTYLE consolidation, Copilot runbook, CI quota - #180

Merged
ptr727 merged 20 commits into
mainfrom
develop
Jun 22, 2026
Merged

Promote develop to main: CODESTYLE consolidation, Copilot runbook, CI quota#180
ptr727 merged 20 commits into
mainfrom
develop

Conversation

@ptr727

@ptr727 ptr727 commented Jun 22, 2026

Copy link
Copy Markdown
Owner

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

Notes

ptr727-codegen Bot and others added 20 commits June 9, 2026 05:33
@ptr727-codegen
Update codegen files (#133)
27bb84c 
This PR updates the codegen files.

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

Co-authored-by: ptr727-codegen[bot] <275599072+ptr727-codegen[bot]@users.noreply.github.com>
@ptr727-codegen
Update codegen files (#138)
032b3b0 
This PR updates the codegen files.

Co-authored-by: ptr727-codegen[bot] <275599072+ptr727-codegen[bot]@users.noreply.github.com>
@ptr727-codegen
Update codegen files (#140)
5aa1fd0 
This PR updates the codegen files.

Co-authored-by: ptr727-codegen[bot] <275599072+ptr727-codegen[bot]@users.noreply.github.com>
@ptr727-codegen
Update codegen files (#142)
2ddf924 
This PR updates the codegen files.

Co-authored-by: ptr727-codegen[bot] <275599072+ptr727-codegen[bot]@users.noreply.github.com>
@ptr727-codegen
Update codegen files (#143)
8b961da 
This PR updates the codegen files.

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

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

Co-authored-by: ptr727-codegen[bot] <275599072+ptr727-codegen[bot]@users.noreply.github.com>
@ptr727-codegen
Update codegen files (#149)
48b5fc8 
This PR updates the codegen files.

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

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

Co-authored-by: ptr727-codegen[bot] <275599072+ptr727-codegen[bot]@users.noreply.github.com>
@ptr727
Decouple verbatim-carry runbook, clarify versioning, list downstreams (…
7d96465 
…#156)

## Summary

Three related template-contract fixes surfaced while re-syncing
`ptr727/NxWitness` (NxWitness#439).

### 1. Resolve #155 — keep `.github/copilot-instructions.md` carry-safe
(Option 2: decouple)
The mandated whole-file verbatim carry embedded template-only
assumptions that broke once carried into a conforming derived repo
(whose only mandated AGENTS.md section is *PR Review Etiquette*):
- Dropped the "what NOT to touch" / "files you must not touch"
overstatements.
- Removed the template-specific versioning paragraph (also clears the
`#release-model` dangling anchor).
- Replaced the pre-carry `<owner>/<repo>/<N>` blockquote with a clean
runbook-purpose line (clears the `#files-and-sections…` dangling
anchor).
- Retargeted the staying-in-sync ref to an explicit upstream-template
URL.

Every remaining local `../AGENTS.md#` anchor now resolves only to the
mandated `#pr-review-etiquette`.

### 2. Clarify versioning — remove the mandatory develop lead /
post-release bump
`version.json` is now bumped **only for functional changes, by
maintainer instruction**, not mechanically after a release. `develop`
builds are always prereleases, so they need no artificial minor lead and
there is no `bump-version-X.Y` PR or `git checkout main -- version.json`
trick. Updated AGENTS.md *Release Model* and the README branching
bullet.

### 3. Add a Known Downstream Projects catalog
New table in AGENTS.md *Staying in Sync* (NxWitness, PlexCleaner,
Utilities, LanguageTags, ESPHome-NonRoot, VSCode-Server-DotNetCore,
homeassistant-purpleair) with each repo's consumer model, plus the
maintainer-facing direction to file heads-up issues downstream on
contract changes — making the sync explicitly bidirectional. README
points adopters to it and reinforces filing upstream issues.

## Verification
- markdownlint-cli2 clean on all three files.
- Old mechanical-lead rules grep-clean (only the new negation bullet
remains).
- All files remain fully CRLF; new anchors resolve.
@ptr727-codegen
Update codegen files (#166)
cad6289 
This PR updates the codegen files.

Co-authored-by: ptr727-codegen[bot] <275599072+ptr727-codegen[bot]@users.noreply.github.com>
@ptr727
Resummarize template docs and trim workflow comments (#167)
212d8a8 
Acts on the issues surfaced while porting ESPHome-NonRoot to the
template (#157-#164), plus the comment/doc cleanup and CI-storage
feedback.

## Docs
- New **Comments house-rule** in AGENTS.md (concise, current-state, no
cross-project references, no rule citations, match ~120-col) - applied
throughout.
- copilot-instructions.md resummarized: dropped the duplicated PR-title
block and historic narrative, kept the Copilot review runbook mechanics.
- Bless trailing-backslash hard line breaks (#164); clarify the
cross-repo boundary (the template hub keeps the
consistency/fan-out/Known-Downstream rules, derived repos never name
siblings); simplify the `version.json` bump rule; document the
HISTORY.md + README release-notes and CODESTYLE-aggregate patterns.

## Workflow comments (#162)
- Trimmed ~300 comment lines across `.github/workflows/*`. Only comments
changed (no logic), CRLF endings and action SHA-pins preserved.

## Doc-clarification issues
- **#158** image tag is build-layer-owned; **#159** verbatim-vs-owned
boundary in `test-pull-request.yml`; **#160** `.editorconfig` C# block
marked .NET-only + first-time `.gitattributes` normalization; **#163**
brownfield re-sign procedure rewritten (filter-branch + committer
rewrite, ruleset ordering, API verification, cleanup). Also clarified
that the maintainer-only force-push is restricted because it is
destructive, not a signing concern.

## New reusable tasks
- **#161** `publish-docker-readme-task.yml` + `Docker/README.md`, wired
into `publish-release.yml`.
- **#157** `check-upstream-version-task.yml` + `merge-upstream-version`
wiring for wrapper repos that track an upstream release; state file
standardized at the repo root.

## CI storage
- `retention-days: 1` on all intermediate build artifacts (was 90-day
default); documented the artifact-retention and registry-cache
(`type=registry`, not `type=gha`) conventions.

## README
- Added a **Deferred Patterns** backlog (unit-test factoring,
per-language test scaffolds).

Verified: actionlint clean, markdownlint clean, all touched `.yml`/`.md`
CRLF, all actions SHA-pinned.
@ptr727 @claude
check-upstream-version-task: structured multi-key JSON state (#169)
7566c39 
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 @claude
Write upstream-version state file as CRLF to honor the JSON rule (#172)
38f46ea 
Closes #170. Supersedes #171 (which took the wrong approach — see
below).

## Problem

`check-upstream-version-task.yml` wrote the state file with `printf
'%s\n'` on the runner — **LF** — but `.editorconfig` defaults
`.json`/`.jsonc` to **CRLF**. The committed `upstream-version.json`
therefore contradicted the repo's own rule: open it in an
`.editorconfig`-aware (or vanilla Windows) editor and save, and it flips
to CRLF, so the next tracker run rewrites it back to LF — a spurious
`Canonicalize upstream version state file` PR.

## Why not carve the file out to LF (the closed #171 / issue option 2)

The whole point of defaulting JSON to CRLF is that **Windows
vanilla-editor saves don't break things**. Carving the state file out to
LF inverts that — a Windows save produces CRLF and now violates the
carve-out, churning on exactly the platform the CRLF rule protects. So
the fix belongs in the task, not in a special case.

## Fix (issue option 1)

Write the state file with **CRLF**, honoring `.editorconfig`'s rule for
`.json` with no per-file carve-out. `jq` emits LF, so convert line
endings on write:

```sh
printf '%s\n' "$new" | sed 's/$/\r/' > "$STATE_FILE"
```

`.editorconfig` and `.gitattributes` are untouched.

## Validation

- Output is CRLF (`file` → `JSON text data`, `cat -A` → `^M$` line ends)
and **idempotent**: rewriting identical content is byte-for-byte
identical, so no churn / no spurious PR.
- `jq -S '.'` still round-trips the CRLF file, so the old-state read and
union diff are unaffected (comparison is on parsed objects,
EOL-agnostic).
- A Windows vanilla-editor save now produces CRLF that **matches** the
committed file.
- YAML parses.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@ptr727 @claude
Clarify project rules belong in AGENTS.md, harden Copilot review runbook
cde3354 
Two template-doc gaps surfaced while re-syncing ptr727/LanguageTags.

State that project-specific conventions and API/behavioral contracts belong in
AGENTS.md (the agent-agnostic file every coding agent is directed to read),
keeping .github/copilot-instructions.md narrow - the Copilot runbook plus the
inline commit/PR-title summary.

Harden the Copilot review runbook: a review with no inline comments is a
completed clean pass, round 1 is auto-seeded and should be polled for before
self-triggering, and the bot-id/seed decision keys on the formal review.

Closes #173

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@ptr727-codegen
Update codegen files (#176)
e8dbb0c 
This PR updates the codegen files.

Co-authored-by: ptr727-codegen[bot] <275599072+ptr727-codegen[bot]@users.noreply.github.com>
@ptr727 @claude
Skip artifact uploads on PR smoke builds to cut quota usage
402e862 
PR smoke builds (test-pull-request.yml -> build-release-task.yml smoke:true)
uploaded build artifacts that nothing consumes on a PR: github-release and the
executable aggregation are gated !smoke, and publish-pypi runs only on a real
publish. Those orphaned uploads churned the Actions artifact-storage quota on
every target-touching PR.

Gate the uploads on !inputs.smoke so smoke builds still compile/lint/test but
persist nothing; publish runs (smoke:false) upload and consume as before:
- build-nugetlibrary-task / build-pypilibrary-task: add a smoke input; skip the
  release-asset / wheel-sdist upload.
- build-executable-task: skip the per-runtime publish-* matrix upload.
- build-release-task: forward smoke to the nuget and pypi tasks.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@ptr727 @claude
Consolidate code style into one CODESTYLE.md and govern tasks
f526b55 
Surfaced while re-syncing ptr727/Utilities; addresses the CODESTYLE carry-contract
gaps in #175 plus related governance.

- Merge PyPiLibrary/CODESTYLE.md into a single root CODESTYLE.md structured as
  General -> .NET -> Python, each language section droppable (the .editorconfig
  [*.cs] boundary model). CODESTYLE.md becomes a verbatim-carry artifact with
  marked adapt-zones and load-bearing repo-root placement.
- General-section rules: official-tooling casing; a per-language clean-compile
  verification (named tasks/commands, carried verbatim, tasks.json is the
  canonical spec, run after every edit); and a suppression scope hierarchy where
  brownfield is never a license to relax severities.
- Govern .vscode/tasks.json: rename labels .Net* -> .NET* (and launch.json),
  add dependsOrder: sequence to the .NET Format task, mark the clean-compile
  group carried-verbatim vs convenience/project-specific tasks.
- Wire the carry contract and pointers through AGENTS.md, README, and
  .github/copilot-instructions.md.

Admin-merged: the only failing check was the GitHub Actions artifact-storage
quota (infra), not this change; unit tests, ruff/pyright/pytest, markdownlint,
and the Copilot review all passed.

Closes #175

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Copilot AI review requested due to automatic review settings June 22, 2026 18:12
Copilot AI reviewed Jun 22, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

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

Changes:

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

Reviewed changes

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

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

Comment thread .github/workflows/build-pypilibrary-task.yml
@ptr727
ptr727 merged commit 737b6ce into main Jun 22, 2026
21 checks passed
@ptr727 ptr727 mentioned this pull request Jun 22, 2026
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot
Copilot review effort
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

2 participants

@ptr727