Conversation
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. - **README "Rules / Rulesets" caveat:** renaming or updating an existing ruleset via API needs a **full-payload PUT**, not name-only - a partial update 422s with `Unexpected parameter 'allowed_dismissal_actors'` because GitHub re-validates the stored `pull_request` rule (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 legacy `Develop`/`Main` rulesets to `develop`/`main` on LanguageTags and NxWitness. - **AGENTS verbatim-carry list:** on first adoption of `.markdownlint-cli2.jsonc`, a repo's docs usually have pre-existing structural debt (MD022/MD031/MD032/MD040). Documented the `markdownlint-cli2 --fix` one-pass cleanup, the manual MD040 fence-labeling, and the **re-verify-CRLF** caution (`--fix` can rewrite a CRLF file as LF - hit this on Utilities). markdownlint clean (0 errors); CRLF preserved.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR promotes documentation refinements from develop to main, capturing operational lessons from downstream realignments so derived repos inherit the updated guidance.
Changes:
- Document a ruleset-renaming/editing caveat: ruleset updates may require a full-payload PUT (README).
- Extend the verbatim-carry guidance with a first-adoption
markdownlint-cli2 --fixcleanup step and a CRLF re-check warning (AGENTS). - Correct US-English spelling (
judgement->judgment) in the review-triage guidance (AGENTS).
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| README.md | Adds a ruleset update/rename caveat and a safe GET-edit-PUT flow to avoid partial-update failures. |
| AGENTS.md | Fixes spelling and documents first-time markdownlint adoption steps including --fix cleanup and EOL re-verification. |
Fixes three comment/consistency nits surfaced by Copilot on the downstream promotion PRs (the same template config propagated to derived repos, so fixing it here corrects the source - downstream picks it up on re-sync): - **`.markdownlint-cli2.jsonc`:** the `MD060` comment was wrong - MD060 is the **table-column-style** rule (pipe/column spacing), not about wide or wrapping tables. Rewrote it to say we don't enforce a table pipe-spacing style. - **`.editorconfig`:** the JSON section globs `json,jsonc` now, so the `# Json files` header is updated to `# Json and JsonC files`. - **`AGENTS.md`:** the markdownlint `--fix` first-adoption step now uses the Docker invocation (consistent with "Running the Linters Locally") instead of a bare `markdownlint-cli2` command. markdownlint clean; CRLF preserved.
Reconciles a wording tension Copilot flagged on the promotion PR: the new ruleset-rename caveat said the name is "not load-bearing", which could read as contradicting the earlier requirement that repos end up with the exact `develop`/`main` ruleset names. Clarified that the rename is safe for *enforcement* (the required status-check binds by check name), while the template still expects the standard names.
Shell-correctness nit from Copilot on the promotion PR: the inline `gh api -X PUT repos/<owner>/<repo>/rulesets/<id>` example had an unquoted URL, so a shell would interpret `<owner>`/`<repo>`/`<id>` as redirections. Quoted it to match the other `gh api "repos/<owner>/<repo>/..."` examples in the same section.
This was referenced Aug 22, 2026
Merged
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.
Promotes
developtomain: template-doc refinements captured from the downstream realignment - the ruleset full-payload-PUT caveat (README) and the markdownlint--fixfirst-adoption step incl. CRLF re-check (AGENTS), plus the US-English 'judgment' fix. (#126)