Re: [PATCH 1/4] gitweb: notes feature

Johan Herland [off-list ref] writes:

I already maintain a TODO list at the end of the cover letter to the notes 
series. Here is a preview of it (I plan to send the next iteration of 
jh/notes as soon as v1.7.0 is released):
...

Random additional thoughts.

* Futureproofing

We have to admit that our notes support, especially on the output side, is
still in its infancy.  We may want to advertise it as such -- highly
experimental and subject to change.

* format-patch

To add notes to format-patch output, we might want to do something like:

    $ git format-patch --notes-ref=commits --notes-ref=amlog -1

and produce:

    From 8bff7c5383ed833bd1df9c8d85c00a27af3e5b02 Mon Sep 17 00:00:00 2001
    From: Andrew Myrick [off-list ref]
    Date: Sat, 30 Jan 2010 03:14:22 +0000
    Subject: [PATCH] git-svn: persistent memoization
    X-Notes: pulled on Fri Feb 5 07:36:12 2010 -0800
     from git://git.bogomips.org/git-svn.git/
    X-Notes-amlog: [off-list ref]

    Make memoization of the svn:mergeinfo processing functions persistent with
    ...

Points to notice:

 - There is no point forcing users to spell "--notes-ref" parameter
   starting from refs/notes/; we should DWIM if they are missing;

 - We would want to allow more than one notes hierarchy specified. This
   would affect format_note() function---take list of struct notes_tree,
   perhaps;

 - Allow callers of tell format_note() to add the name of the notes
   hierarchy the note came from (or just always add it if it is not the
   default "refs/notes/commits").

 - For format-patch that produces a mbox output, the email header part may
   be a better place to put notes (obeying the usual "indent by one space
   to continue the line" convention).

* "log --format=%N" and "log --show-notes"

Currently %N expands to the hardcoded "log --show-notes" default format.
We can probably keep it that way.  When the user asked for a non default
notes hierarchy (i.e. other than refs/notes/commits), we may want to
adjust "Notes:" string to use "Notes-%s:" to show which hierarchy it came
from, and concatenate them together.

For "log --show-notes" output, we also might want to move the notes to the
header part like I illustrated above in format-patch output, instead of
"start with unindented Notes: and indented body at the end".  I.e. instead
of showing this:

    $ git log --notes-ref=amlog -1 4d0cc22
    commit 4d0cc2243778b38c3759c6a08f4f1ed64155a070
    Author: Junio C Hamano [off-list ref]
    Date:   Thu Feb 4 11:10:44 2010 -0800

        fast-import: count --max-pack-size in bytes

        Similar in spirit to 07cf0f2 (make --max-pack-size argument to 'git
        ...
        Acked-by: Nicolas Pitre [off-list ref]

    Notes:
        [off-list ref]


show it like this:

    $ git log --notes-ref=amlog -1 4d0cc22
    commit 4d0cc2243778b38c3759c6a08f4f1ed64155a070
    Author: Junio C Hamano [off-list ref]
    Date:   Thu Feb 4 11:10:44 2010 -0800
    Notes-amlog: [off-list ref]

        fast-import: count --max-pack-size in bytes

        Similar in spirit to 07cf0f2 (make --max-pack-size argument to 'git
        ...
        Acked-by: Nicolas Pitre [off-list ref]

On Fri, Feb 5, 2010 at 5:10 PM, Junio C Hamano [off-list ref] wrote:

* format-patch

To add notes to format-patch output, we might want to do something like:

   $ git format-patch --notes-ref=commits --notes-ref=amlog -1

and produce:

   From 8bff7c5383ed833bd1df9c8d85c00a27af3e5b02 Mon Sep 17 00:00:00 2001
   From: Andrew Myrick [off-list ref]
   Date: Sat, 30 Jan 2010 03:14:22 +0000
   Subject: [PATCH] git-svn: persistent memoization
   X-Notes: pulled on Fri Feb 5 07:36:12 2010 -0800
    from git://git.bogomips.org/git-svn.git/
   X-Notes-amlog: [off-list ref]

+1 for header style note exporting. X-Git-Notes might be better.

Points to notice:

 - There is no point forcing users to spell "--notes-ref" parameter
  starting from refs/notes/; we should DWIM if they are missing;

Agreed.

 - We would want to allow more than one notes hierarchy specified. This
  would affect format_note() function---take list of struct notes_tree,
  perhaps;

I get the impression everybody wants this ;-)

 - Allow callers of tell format_note() to add the name of the notes
  hierarchy the note came from (or just always add it if it is not the
  default "refs/notes/commits").

This is probably the most bothering issue: find, for each output
format that involves notes, the smart way of also outputting the
namespace it came from.

 - For format-patch that produces a mbox output, the email header part may
  be a better place to put notes (obeying the usual "indent by one space
  to continue the line" convention).

How would you cope with multi-line notes? One X-Git-Notes header per line?

* "log --format=%N" and "log --show-notes"

Currently %N expands to the hardcoded "log --show-notes" default format.
We can probably keep it that way.  When the user asked for a non default
notes hierarchy (i.e. other than refs/notes/commits), we may want to
adjust "Notes:" string to use "Notes-%s:" to show which hierarchy it came
from, and concatenate them together.

We might want to do without the dash in standard log output: Notes:
and Notes <namespace>:

For "log --show-notes" output, we also might want to move the notes to the
header part like I illustrated above in format-patch output, instead of
"start with unindented Notes: and indented body at the end".  I.e. instead
of showing this:

   $ git log --notes-ref=amlog -1 4d0cc22
   commit 4d0cc2243778b38c3759c6a08f4f1ed64155a070
   Author: Junio C Hamano [off-list ref]
   Date:   Thu Feb 4 11:10:44 2010 -0800

       fast-import: count --max-pack-size in bytes

       Similar in spirit to 07cf0f2 (make --max-pack-size argument to 'git
       ...
       Acked-by: Nicolas Pitre [off-list ref]

   Notes:
       [off-list ref]


show it like this:

   $ git log --notes-ref=amlog -1 4d0cc22
   commit 4d0cc2243778b38c3759c6a08f4f1ed64155a070
   Author: Junio C Hamano [off-list ref]
   Date:   Thu Feb 4 11:10:44 2010 -0800
   Notes-amlog: [off-list ref]

       fast-import: count --max-pack-size in bytes

       Similar in spirit to 07cf0f2 (make --max-pack-size argument to 'git
       ...
       Acked-by: Nicolas Pitre [off-list ref]

The footer approach has the benefit of allowing multi-line notes to
just be printed the same way as multi-line commit messages, whereas
the header output would require one header line per commit line.

-- 
Giuseppe "Oblomov" Bilotta