Link to issue number:

Part of #12387

Summary of the issue:

The NVDA code base uses a mix of CRLF and LF style line endings, with the preference being CRLF.
LF style endings have been introduced prior to lint checking, and can causes issues when moving code or making changes.
Many IDEs will normalize the line endings when editing files, causing larger than intended diffs of files with mixed line endings.
Instead, we should normalize all line endings of text files to LF and ensure that all files are committed with LF line endings.

Specific files should be excluded from normalization such as:

• files used by translators, as we are uncertain of the side-effects here
• binary files

git allows independent configurations between line endings used when a developer checkouts out code locally, and when code is committed to a repository.
IDEs are often better suited for different line endings, with LF line endings becoming more and more standardised.
However, NVDA is Windows based development, where CRLF line ending usage is commonly default or compulsory.
Developers can checkout code locally, using whatever line endings they prefer or their IDE requires, using git config.core autocrlf.

We can configure what line endings we commit to the repository with .gitattributes.
This is set on a repository level.
As what line endings we commit with is agnostic to what is checked out, the decision is based on what works best for the repository.
Unix style line endings usage and support continues to increase on Windows and LF files.
LF tends to be better supported by Unix style developer tools such as git.
LF uses less data than CRLF.

Additional information: https://docs.github.com/en/get-started/getting-started-with-git/configuring-git-to-handle-line-endings

Description of how this pull request fixes the issue:

Fixing this is a 3 step process, this PR emulates the 3 steps, but only one commit should be merged at a time.

1. The first commit updates .gitattributes so that any new files committed will use LF style endings where appropriate.
2. Then, no PRs should be merged until a commit which normalizes the line endings is committed to master.
   Otherwise, new PRs will have large diffs due to line ending changes.

   git pull origin/master # to get .gitattributes
   git add --renormalize .
   git commit -m "fix line endings"

3. Then, the third commit can be committed. This updates the .git-blame-ignore-revs file so that the normalization commit can be ignored by developers using git blame.

Specifically this PR:

• Updates .gitattributes file, with eol=lf and normalization patterns for each file type NVDA uses:
  • -text or binary for no normalization
  • text to change line endings to lf when committing code.
• Ensures git add --renormalize . sets the correct line endings for the entire project.
• Updates documentation

Testing strategy:

Setup normalize-line-endings as follows to perform this testing.

git checkout normalize-line-endings
git reset origin/normalize-line-endings --hard
git add --renormalize .
git commit -m "fix line endings"

Update .git-blame-ignore-revs with the latest commit.

Compare the diff while ignoring eol line changes

git diff --ignore-cr-at-eol origin/master normalize-line-endings

Check the blame of a file from this branch and confirm the line ending changes show up in the blame.

Then check the blame of a file:

git blame source/core.py normalize-line-endings

Test that .git-blame-ignore-revs works and ignores the line ending changes.

git blame --ignore-revs-file .git-blame-ignore-revssource/core.py normalize-line-endings

Test that setting .git-blame-ignore-revs works.

This should be recommended to devs.

git config --local blame.ignoreRevsFile .git-blame-ignore-revs
# should ignore revs
git blame source/core.py normalize-line-endings
# should not ignore revs
git blame --ignore-revs-file "" source/core.py normalize-line-endings

Test that committing a text file, not used by the translation system, with CRLF line endings is not possible.

This can be done by adding or changing a file.

Test that the resulting translation .pot files generated do not change after nomalization.

git checkout master
scons pot
git checkout normalize-line-endings
scons pot

Note: Not git diff, as these files are ignored. Update the commits within the file names if required.

diff output/nvda_snapshot_source-master-6b4cf45.pot output/nvda_snapshot_source-normalize-line-endings-31dee0a.pot

cat -A displays CR as ^M. This will ensure the diff tool picks up on any CRLF changes.

cat -A output/nvda_snapshot_source-master-6b4cf45.pot > master-with-explicit-line-endings.pot
cat -A output/nvda_snapshot_source-normalize-line-endings-31dee0a.pot > normalized-with-explicit-line-endings.pot
diff master-with-explicit-line-endings.pot normalized-with-explicit-line-endings.pot

Known issues with pull request:

None

Change log entries:

N/A

Code Review Checklist:

• Pull Request description is up to date.
• Unit tests.
• System (end to end) tests.
• Manual testing.
• User Documentation.
• Change log entry.
• Context sensitive help for GUI changes.
• UX of all users considered:
  • Speech
  • Braille
  • Low Vision
  • Different web browsers

Summary by CodeRabbit

• Documentation

  • Added detailed usage guidelines for the git-blame-ignore-revs feature.
  • Updated codingStandards.md with new file encoding and line ending practices, naming conventions, and docstring format specifications.

• Chores

  • Modified .gitattributes to set eol=lf, define text attributes for various file types, and specify files exempt from renormalization.