Refine line-ending policy, default Python to CRLF, add runbook notes - #229
Merged
Conversation
Update the AGENTS.md Line Endings section to describe the `[*] end_of_line = crlf` default with LF exceptions - matching the merged editorconfig - instead of prescribing the old full-per-extension form, and add an EOL-audit note (byte-scan over `file`/`git ls-files --eol`, scope to `git ls-files`, multi-line edits emit CRLF, .code-workspace is JSONC). Add a Git rule to check the maintainer's uncommitted edits before committing. Add copilot-instructions runbook gotchas: `gh pr edit` is broken (Projects-classic deprecation) so edit via updatePullRequest/PATCH; main/develop use rulesets not classic protection; the push -> head-SHA read race; and that Copilot findings can be factually wrong. Encodes retrospective #228 learnings (line endings, gh/Copilot mechanics, pre-commit checks). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Pieter Viljoen <ptr727@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the repository governance docs to (1) align the documented line-ending policy and auditing guidance with the current .editorconfig/.gitattributes shape, and (2) add operational runbook notes about PR editing and merge-state interpretation in the GitHub CLI/Copilot workflow.
Changes:
- Add a Git rule to check for maintainer-owned uncommitted working-tree edits before committing.
- Reconcile and expand the Line Endings section, including an EOL-audit approach and JSONC note for
.code-workspace. - Add PR-runbook "gotchas" about
gh pr edit, rulesets vs classic protection, head-SHA read races, and verifying Copilot findings.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| AGENTS.md | Updates commit workflow guidance and reconciles/extends the documented line-ending policy and auditing procedure. |
| .github/copilot-instructions.md | Adds a runbook subsection capturing PR-edit and merge-state troubleshooting gotchas. |
Classify EOL audits as CRLF-only / LF-only / mixed (flag mixed, not lump into CRLF); use an explicit body-file name in the REST PATCH example; and correct the merge-state note (BLOCKED is a mergeStateStatus value, distinct from the mergeable field's MERGEABLE/CONFLICTING). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Pieter Viljoen <ptr727@users.noreply.github.com>
Vanilla .py now follows the [*] = crlf default: Python's universal newlines accept CRLF, it compiles/imports/runs identically, and .py is commonly edited on Windows - a blanket LF pin just caused LF<->CRLF save-churn there. Pin LF only for a .py executed directly via its shebang, by path - spec/validate.py, the CI validation entry point - in both .editorconfig and .gitattributes, and drop the blanket *.py LF pin. Updates the AGENTS.md line-ending summary; revises #228 s1's blanket [*.py]=lf. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Pieter Viljoen <ptr727@users.noreply.github.com>
ptr727
changed the title
This was referenced Jul 5, 2026
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.
Encodes the validated, non-conflicting slice of retrospective #228, plus a line-ending policy refinement.
[*] end_of_line = crlfdefault + LF-exceptions policy (it previously prescribed the old full-per-extension form and warned against the minimal form). Default.pyto CRLF - Python's universal newlines accept CRLF, so it imports/runs/compiles identically on every OS, and.pyis commonly edited on Windows where a blanket LF pin only caused LF<->CRLF save-churn. Pin LF by path for a.pyexecuted directly via its shebang (spec/validate.py, the CI validation entry point), treating it like a shell script; drop the blanket*.py text eol=lf. This revises Retrospective: cross-platform, dev-tooling & agent-workflow learnings to encode as rules #228 §1's blanket[*.py] = lf.fileor naivegit ls-files --eolparsing; scope audits togit ls-files(+--others --exclude-standard); multi-line / new-file edits into a CRLF file must emit CRLF;.code-workspaceis JSONC.gh pr editis broken by the Projects-classic deprecation (useupdatePullRequest/ REST PATCH);main/developuse rulesets, not classic protection (BLOCKED is usually unresolved threads); the push -> head-SHA read race; Copilot findings can be factually wrong.First of several scoped slices (per #228's own sprawl warning). Decided/deferred items follow in separate PRs: the cross-platform decision procedure (§0), versioning gotchas (§4), markdown hygiene + the cspell
en-USfix (§7), the Python HA-integration profile (§3), and the editor/scripts catalog snippets (§2).🤖 Generated with Claude Code