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

[Junio C Hamano <gitster@pobox.com>]

sideshowbarker <mike@w3.org> writes:

> ## 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.

And even if they did, they wouldn't know how to use them, so not
much is lost here.

Quite honestly, a project that uses notes in such a way that it is
essential to understand/utilize the history should reexamine its use
of notes and try to see if they can make its commits more useful
without relying on notes, I would think.

> 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.

I've seen from time to time people ask "I am thinking of doing this;
will a patch be accepted?  If so, I'll work on it." before showing
any work, and my response always has been:

 (1) We don't know how useful and interesting your contribution would
     be for our audience, until we see it; and

 (2) If you truly believe in your work (find it useful, find writing
     it fun, etc.), that should be incentive enough for you to work
     on it, whether or not the result will land in my tree.  You
     should instead aim for something so brilliant that we would
     come to you begging for your permission to include it in our
     project.

> 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.

A much more light-weight alternative would be to add an example to
the tutorial to tweak the "remote.origin.fetch" refspec so that it
will also fetch notes.

But stepping back a bit, none of the above (including your two) may
practically be workable unless you limit the source of the notes to
the upstream, or something.  If you add notes yourself after you
clone, and the upstream makes different changes to its notes,
reconciling the diverged history of the notes tree would not be so
pleasant.  As a mechanism for the only publisher to publish
auxiliary pieces of information to cloners, notes is a very useful
mechanism, but for such a use case to be effective, the project
participants must understand when they are supposed to use the notes
read-only.