Propagate template contract to derived repos: lint config, review-loop carry, brownfield migration - #124
Merged
Merged
Conversation
…p carry, brownfield migration Ship a shared .markdownlint-cli2.jsonc so the IDE extension and CLI/CI markdownlint-cli2 stay in lock-step, and add jsonc to the .editorconfig JSON glob so the new config is CRLF-governed. (Fixes #116) Make the verbatim-copy contract explicit: mark the AGENTS.md PR Review Etiquette section and the .github/copilot-instructions.md runbook as mandatory verbatim carries for derived repos, add a canonical 'Files and Sections Derived Repos Must Carry Verbatim' list plus a 'Staying in Sync and Reporting Drift Upstream' section, and wire the README TODO list to it. Also mandate carrying .editorconfig + .gitattributes to stop LF/CRLF drift. (Fixes #117) Document the brownfield required_signatures migration (re-sign, disable enforcement to force-push since the admin bypass does not cover git push --force, re-enable), tighten Step 0 to delete ALL legacy protection, and name the JSON export/import as the only ruleset-config method. (Fixes #111)
…a Docker) Workflow YAML and Markdown are linted locally, not in CI, so an agent must know how to run the tools - and their non-Docker install paths (curl-pipe, global npm) are often sandbox-blocked or fail on WSL. Add a 'Running the Linters Locally' subsection to AGENTS.md with the known-working Docker invocations for actionlint (bundles shellcheck) and markdownlint-cli2, plus the empty-DOCKER_CONFIG workaround for the Docker-Desktop/WSL credential-helper error. Quote $GITHUB_OUTPUT in build-datebadge-task.yml so the documented actionlint command exits clean (SC2086).
Contributor
There was a problem hiding this comment.
Pull request overview
This PR propagates template-level cross-cutting contracts (markdown lint configuration, Copilot review-loop runbook discoverability, and brownfield required_signatures migration guidance) back into the template so derived repositories stay consistent and avoid re-solving the same setup defects.
Changes:
- Add a shared
.markdownlint-cli2.jsoncat the repo root and document it as the authoritative markdownlint configuration. - Make the “verbatim carry” contract explicit for derived repos (review-loop contract + runbook, lint config, and line-ending governance files), including guidance for resyncing and reporting upstream drift.
- Document a brownfield migration procedure for adopting
Require signed commitswhen legacy history is unsigned.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | Extends derived-repo checklist and adds brownfield signed-commit migration guidance under rulesets setup. |
| CODESTYLE.md | Declares .markdownlint-cli2.jsonc as the single source of truth for markdownlint behavior (IDE + CLI). |
| AGENTS.md | Adds explicit “carry verbatim” requirements, resync/upstream-drift guidance, and links to brownfield migration docs. |
| .markdownlint-cli2.jsonc | Introduces shared markdownlint-cli2/jsonc configuration to align IDE and CLI linting. |
| .github/copilot-instructions.md | Marks the Copilot review runbook as a verbatim-carry artifact and adds upstream-issue guidance for derived repos. |
| .editorconfig | Expands JSON EOL rules to include *.jsonc to keep the new config CRLF-governed. |
This was referenced Jun 8, 2026
…ner-only force-push Prefer 'git rebase --rebase-merges --exec ...-S' to re-sign (filter-branch is deprecated, kept as a documented fallback), and mark the force-push as a one-time maintainer-only manual step that agents must never run - reconciling the procedure with AGENTS.md's 'Never force push' rule.
ptr727
added a commit
that referenced
this pull request
Jun 8, 2026
Promotes `develop` to `main`. - **#124** - Propagate template contract to derived repos: shared `.markdownlint-cli2.jsonc` (#116), explicit verbatim-copy contract + line-ending mandate + upstream-defect-reporting contract (#117), brownfield `required_signatures` migration (#111), and known-working actionlint/markdownlint Docker linter guidance. Review-loop feedback applied (modern re-sign, maintainer-only force-push). - **#123 / #120 / #119** - Update codegen files.
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.
Folds three downstream-filed defects back into the template so future derived projects don't re-hit them. All three were surfaced while porting the template into KiCadLibrary (#116, #117) and Utilities (#111).
#116 - shared markdownlint config
.markdownlint-cli2.jsoncat the repo root. Both the davidansonmarkdownlintIDE extension and CLI/CImarkdownlint-cli2read it, so the IDE and command line stay in lock-step (previously a CLI run flagged MD013/MD033 errors the IDE showed clean).jsoncto the.editorconfig[*.{json,jsonc}]glob so the new config is CRLF-governed.CODESTYLE.mdat the config as authoritative (kept local-only, no CI gate).#117 - make the verbatim-copy contract explicit (template docs only, no downstream files touched)
AGENTS.md"PR Review Etiquette" section and the.github/copilot-instructions.md"GitHub Copilot Review Runbook" as mandatory verbatim carries for derived repos.AGENTS.md; wire the README TODO list and the copilot-instructions "When in Doubt" to them..editorconfigand.gitattributesto stop files drifting between LF and CRLF (a real failure seen across ports).ptr727/ProjectTemplaterather than only patching locally.#111 - brownfield required_signatures migration
git push --force, re-enable).AGENTS.mdbranching model.Verified:
markdownlint-cli2 "**/*.md"reports 0 errors across all 10 files; all touched files retain CRLF endings.Fixes #116
Fixes #117
Fixes #111