Document ruleset full-payload PUT and markdownlint --fix adoption - #126
Merged
Conversation
…om downstream realignment) Two lessons learned while realigning derived repos, captured in the durable docs so they propagate downstream: - README 'Rules / Rulesets': renaming/updating an existing ruleset needs a full-payload PUT (name-only 422s on a hidden allowed_dismissal_actors param); GET, change the field, PUT the whole writable subset, and verify protections. - AGENTS verbatim-carry list: on first adoption of the shared markdownlint config, run 'markdownlint-cli2 --fix' to clear pre-existing structural debt, hand-label remaining MD040 fences, and re-verify CRLF (--fix can flip endings).
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the template documentation to capture two operational lessons that came up while re-aligning derived repositories, so the guidance propagates downstream on the next re-sync instead of remaining tribal knowledge.
Changes:
- Document that updating/renaming an existing GitHub ruleset via API requires a full-payload
PUTof the writable field subset (not a name-only partial update). - Expand the verbatim-carry guidance for
.markdownlint-cli2.jsoncwith a first-adoption cleanup workflow (--fix, manual MD040 fence labeling) and an explicit CRLF re-verification warning.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| README.md | Adds a ruleset API caveat describing the required GET/edit/full-payload PUT flow for renames/updates. |
| AGENTS.md | Adds first-adoption markdownlint cleanup guidance, including --fix usage and line-ending re-verification caution. |
US-English violation surfaced by a Copilot review on a derived repo that carries this section verbatim (the bidirectional upstream-defect contract in action).
Uh oh!
There was an error while loading. Please reload this page.
ptr727 added a commit
that referenced
this pull request
Jun 8, 2026
Promotes `develop` to `main`: template-doc refinements captured from the downstream realignment - the ruleset full-payload-PUT caveat (README) and the markdownlint `--fix` first-adoption step incl. CRLF re-check (AGENTS), plus the US-English 'judgment' fix. (#126)
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 freeto 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.
Captures two lessons from realigning the derived repos (Utilities/LanguageTags/NxWitness/PlexCleaner) into the durable template docs, so they propagate downstream on the next re-sync rather than living only in a maintainer's head.
Unexpected parameter 'allowed_dismissal_actors'because GitHub re-validates the storedpull_requestrule (which carries fields the GET doesn't return). Documented the GET -> change -> PUT-the-writable-subset -> verify flow. This is exactly what was needed to rename the legacyDevelop/Mainrulesets todevelop/mainon LanguageTags and NxWitness..markdownlint-cli2.jsonc, a repo's docs usually have pre-existing structural debt (MD022/MD031/MD032/MD040). Documented themarkdownlint-cli2 --fixone-pass cleanup, the manual MD040 fence-labeling, and the re-verify-CRLF caution (--fixcan rewrite a CRLF file as LF - hit this on Utilities).markdownlint clean (0 errors); CRLF preserved.