Subject: Problem: git Notes not discoverable (+proposed solutions)

From: sideshowbarker <[email-masked]>
Date: Tue, 23 Jul 2024 14:20:30 +0900

## Problem description

When a project has added git Notes for its commits, git by default doesn’t
automatically fetch the Notes; so, the Notes aren’t automatically discoverable
to contributors who are using “git log” to read the project commit logs — and
especially not discoverable to new contributors, or “casual” users of the logs.

A user will see the Notes only if they _already_ know what git Notes are, and
know that the project uses Notes, and the user knows how to get them.

But the reality is: most users do not even know what git Notes are, and don’t
know how to get them if they exist. So most people end up never seeing them.

## Use-case/requirements

For the Ladybird browser project https://github.com/LadybirdBrowser/ladybird/,
Notes for all 62,000+ commits in its repo commit history were recently added.

And same for the MDN Web Docs project https://developer.mozilla.org/en-US/
and https://github.com/mdn/content/ — Notes were very-recently added for all
23,000+ commits in its history. And that case is a relatively high-visibility
project with a relatively high percentage of new, first-time contributors
submitting patches each month (~33% on average: or ~73 first-time-contributor
patches out of ~361 patches overall that get merged there every month).

(Disclosure: In both cases, I’m the person who added all the Notes…)

The Notes added to those projects provide a variety of relevant GitHub URLs
for each commit — info that’s generally useful to everybody, and not only
useful to say, the project maintainers or the core contributors.

Yet, the projects have no ready way to make the Notes automatically
discoverable/gettable by non-maintainers/core-contributors — and especially,
to be easily discoverable by new people showing up to the project.

I realize the projects can update their docs to tell people they can manually
run “git fetch origin 'refs/notes/*:refs/notes/*'” to fetch Notes — or else do
“git config --add remote.origin.fetch '+refs/notes/*:refs/notes/*'”.

But… people don’t always (or often…) read the docs.

## Patching git: Concrete proposed solutions

I’d be 100% happy to do the work of writing a patch to implement a solution
(a git behavior change) for this — if I could get confirmation that the git
maintainers would actually be open to reviewing such a patch.

As far as what the change would be: I realize this has been brought up
before — but it seems the obvious solutions are to “just” change git so:

- Proposed solution #1: git auto-fetches all Notes when a repo is first cloned,
  and then auto re-fetches them again for every “git fetch” or“git pull”.

  I think that auto-fetching-of-Notes would ideally be the _default_ git
  behavior — but short of that, at least a new [notes] _option_ for enabling
  that behavior would help. That would seem somewhat more “approachable” to
  than “git config --add remote.origin.fetch '+refs/notes/*:refs/notes/*'”.

- Proposed solution #2: git checks if a clone lacks Notes vs remote, and emits:

  > Your clone is behind the origin remote by N notes. To fetch the notes
  > from the origin remote, run “git fetch origin 'refs/notes/*:refs/notes/*'”

Either way, I’d be very willing to put work myself into writing up a patch.

## Details

The Notes added to both the Ladybird and MDN projects provide a variety of
relevant GitHub URLs for each commit — info generally useful to everybody,
and not only useful to say, the project maintainers or core contributors.

For both cases, https://github.com/sideshowbarker/git-gloss/ was used for
adding the Notes. That’s a specialized tool I wrote myself, for adding
GitHub-related Notes which look like this:

  Author: https://github.com/Jon4t4n 🔰
  Commit: https://github.com/SerenityOS/serenity/commit/9812031a02
  Pull-request: https://github.com/SerenityOS/serenity/pull/20140
  Issue: https://github.com/SerenityOS/serenity/issues/19937
  Reviewed-by: https://github.com/AtkinsSJ ✅
  Reviewed-by: https://github.com/nico

That is: for each commit, the Notes include GitHub metadata URLs showing any
GitHub pull-request associated with the commit, along with links to the GitHub
profiles of the pull-request reviewers — as well any related GitHub issues —
along with including a “canonical” URL for the commit, and a link to the
GitHub profile of the commit author

🔰 – indicates this is author’s first commit to the repo
✅ – indicates a review approval

I suspect that over time, a lot of other GitHub-based projects may end up
using that tool to add Notes for their project commits — maybe including some
high-profile projects.

So, ideally, it’d be great to be able to avoid every project needing to
separately document that “git fetch origin 'refs/notes/*:refs/notes/*'” or
“git config --add remote.origin.fetch '+refs/notes/*:refs/notes/*'” are what
people need to do in order to be able to get the Notes.

Instead, ideally, git by default would automatically fetch the Notes for them.
Or, short of that, git would at least emit a message alerting users that Notes
exist at the remote, and explaining to users how they can fetch those Notes.

-- 
https://sideshowbarker.github.io/w3c-faq/