Add .git-blame-ignore-revs

[katcharov]

See:

• https://docs.github.com/en/repositories/working-with-files/using-files/viewing-a-file#ignore-commits-in-the-blame-view
• https://github.com/orgs/community/discussions/5033

This ignores some reformatting commits arising from DRIVERS-2789 when viewing git blame on GitHub and in other tools. Tested auth.md in IntelliJ.

Blame before, note most lines attributed to the Sync with 4b7d757 commit.

Blame after (as of this change). In some cases, tools do not identify the correct commit.

[eramongodb]

Recommend using git log -n 1 --format=format:"%H # %s (%cs)" <hash> to generate entries for this file. e.g.:

ca372f0c6a1353742437d65131b37544492692c2 # Sync with 4b7d7573 (2024-02-26)
634d6399bc166d27f290599d8facf034fa17be91 # Sync with 4b7d7573 (2024-02-26)
405e736abf6884c69669fcc060ef76c44f2e63e7 # Sync with 4b7d7573 (2024-02-26)
...
cea087babea68571fa4068ace6b2d326c3a0a22d # DRIVERS-2789 Convert BSON Corpus Spec to Markdown (#1499) (2024-01-23)
e9ae09da918dc7ca7e5ae12a1af6ca34e9c7854e # DRIVERS-2790 Add codespell checker (#1491) (2024-01-10)
eef59d9d386bb054e0eb59e6bd540a030186f899 # DRIVERS-2789 Use Markdown for Specifications Documentation (#1482) (2024-01-04)

[katcharov]

Used cat .git-blame-ignore-revs | xargs -n1 git log -n 1 --format=format:"%H # %s (%cs)" $1 to update.

[eramongodb]

I'd like to defer my explicit approval/disapproval until more feedback is given by other reviewers. However, I lean towards disapproval (rejecting proposed changes in this PR).

To reiterate my comments from external discussion in short summary, I would rather deal with the presence of the Markdown conversion and the "Sync with" commits in the line-based git blame history over allowing for the possibility of misleading git blame line-to-commit attribution resulting from the use of --ignore-rev on commits with significant change in content. The conversion from reStructuredText to Markdown alone is significant enough for me to be reluctant to ignoring them. The inclusion of "Sync with" commits that restore git blame history, which may also contain important spec changes (e.g. a288630) unrelated to Markdown conversion, further strengthens my reluctance.

Examples of the concerning line-based git blame behavior with ignored refs include (note: use of ~ suffix for hash in URL to disable ignoring revs):

• Line 196 of auth.md. Incorrectly attributed to unrelated commit 5112bcc (April 2023) when it should be:
  • ad2d7a5 (blame without ignore revs): blame prior to change -> eb2e511
  • eb2e511: select annotated revision -> c7494b9
  • c7494b9: the correct commit (March 2018).
• Line 395 of change-streams.md. Incorrectly attributed to 35e466d (May 2018) when it should be:
  • ad2d7a5 (blame without ignore revs): blame prior to change -> dc9394b
  • dc9394b: select annotated revision -> 8978899
  • 8978899: the correct commit (April 2022).
• Line 364 of unified-test-format.md. Incorrectly attributed to ed4e62b (April 2021) when it should be:
  • ad2d7a5 (blame without ignore revs): blame prior to change -> a2efcb9 (dead-end)
  • a2efcb9: line is missing because it came from the "Sync with" commit 634d639 -> blame the file from the commit referenced by the "Sync with" commit instead -> 4b7d757 (dead-end)
  • 4b7d757: no git blame history due to the annotated revision which removed (rather than renamed) the old .rst file -> select annotated revision which broke git blame history -> f017041 -> blame the .rst file from the parent commit (prior to deletion) -> bcde8cd
  • bcde8cd: select annotated revision -> a288630
  • a288630: the correct commit (Jan 2024)

I recommend other reviewers examine the quality of line-based git blame history of affected files when considering the proposed changes in this PR.

[eramongodb]

GitHub's syntax highlighter/linter seems to dislike trailing comments (highlighting lines red), but I believe it should be fine. Per fsck.skipList documentation (the format used by --ignore-revs-file):

On versions of Git 2.20 and later, comments (#), empty lines, and any leading and trailing whitespace are ignored. Everything but a SHA-1 per line will error out on older versions.

And per v2.20 source code:

Allow trailing comments, leading whitespace (including before commits), and empty or whitespace only lines.

If this is undesirable and we want to make GitHub's syntax highlighter/linter happy, we can use git log -n 1 --format=format:"# %s (%cs)%n%H%n%n" instead:

# Sync with 4b7d7573 (2024-02-26)
ca372f0c6a1353742437d65131b37544492692c2

# Sync with 4b7d7573 (2024-02-26)
634d6399bc166d27f290599d8facf034fa17be91

# Sync with 4b7d7573 (2024-02-26)
405e736abf6884c69669fcc060ef76c44f2e63e7

...

However, I recommend sticking with the current format that uses trailing comments.

[blink1073]

I agree with @eramongodb's assessment.

[katcharov]

Alright, I'll close this PR. (The file can at least be applied locally.)