## 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/
Attachment:
signature.asc
Description: PGP signature
