Skip to content

Docs: add CONTRIBUTING guideline against incidental reformatting/refactoring of existing files #1197

Closed

Description

@obit91

Summary

Add an explicit guideline to CONTRIBUTING.md instructing contributors not to reformat, re-indent, change line endings, or refactor unrelated parts of a file when making a scoped change. Incidental formatting changes make a small edit appear as a whole-file rewrite, which makes review very hard (every line shows as a delta) and can hide the real change.

Background — why this is being raised now

This came up during work done by GitHub Copilot on PR bradygaster/squad#1196 (spoiler-awareness casting rule). The intended change was an ~18-line content addition to casting-reference.md. However, the local Git setting core.autocrlf=true normalized the file's committed CRLF line endings to LF, which rewrote every line. The diff showed 122 insertions / 104 deletions instead of the real 18 insertions, 0 deletions, and the file was effectively unreviewable until the line endings were restored.

That specific instance was identified and fixed within the PR (endings restored to CRLF; the diff collapsed to the genuine change only). This issue is to capture the general lesson so it doesn't recur, by documenting the expectation in CONTRIBUTING.md.

Proposed guideline (to add to CONTRIBUTING.md)

  • Keep changes scoped: only touch the lines relevant to your change.
  • Do not reformat, re-indent, reorder, or refactor code/markdown that is unrelated to your change.
  • Preserve existing line endings. If a file is committed with CRLF, keep CRLF. On Windows, be aware that core.autocrlf=true can silently rewrite line endings on commit — stage such files with core.autocrlf=false, or add a .gitattributes rule pinning the file's eol.
  • If a genuine reformat is needed, do it in a separate, dedicated PR so it can be reviewed independently of functional changes.
  • Before pushing, sanity-check git diff --stat / --numstat: if a small change shows a whole-file delta, investigate (usually whitespace or line endings) before committing.

Notes

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions