Re: Suggestions for "What's cooking"

From: Andrew Ardill <andrew.ardill@gmail.com>
Date: Sep 14, 2012, 03:58 UTC
Message-ID: <CAH5451m28z_5Hbtyqx3+YkR-CoTNFB9bjLx6A1cJJXtj3hVjQQ@mail.gmail.com>
In-Reply-To: <7vboh99w1z.fsf@alter.siamese.dyndns.org>

On 14 September 2012 12:29, Junio C Hamano <gitster@pobox.com> wrote:

Show 35 quoted lines

> Andrew Ardill <andrew.ardill@gmail.com> writes:
>
>> On 14 September 2012 04:06, Junio C Hamano <gitster@pobox.com> wrote:
>>> Andrew Ardill <andrew.ardill@gmail.com> writes:
>>>
>>>> <short-branch-description>
>>>>   <long-branch-description>
>>>>   <notes>
>>>>   <next-steps>
>>>>   * <branch-name> (<creation-date>) <number-of-commits>
>>>>     (<merge-status>)
>>>>    [list-of-commits]
>>>>     (<branch-usage>)
>>>
>>> I do not see how it makes any sense to have the "This is where the
>>> section begins with, and its name is this" line in the middle of a
>>> block indented in such a way.  Care to explain?
>>
>> I'm not quite sure what aspect you are referring to,...
>
> Just this part, as I do not have much time.  Here is your reordered
> one I will reject:
>
>   A > jc/maint-blame-no-such-path
>     >   "git blame MAKEFILE" run in a history that has "Makefile" but not
>     >   "MAKEFILE" should say "No such file MAKEFILE in HEAD", but got
>     >   confused on a case insensitive filesystem.
>     >
>   B >   * jc/maint-blame-no-such-path (2012-09-10) 1 commit
>     >    - blame $path: avoid getting fooled by case insensitive filesystems
>
> I was noting that B which *is* formatted as a header line (it EVEN
> has a leading asterisk to make it clear that it begins something
> new) is in the middle, and you added a redundant A that is not even
> marked clearly as a header line.

The leading asterisk is actually not as useful to me, as indicating a header line, as the 'out-denting' I am proposing. I think this is due to the similarities between the asterisk and the other symbols used to indicate commits. This is maybe just a typographic issue, but I think in general the contrast between letters and spaces appearing in the first columns of text is stronger than either of characters and letters, or spaces and characters. A quick comparison of all three:

--Letters and Spaces--
jc/maint-ident-missing-human-name
  "git show --format='%ci'" did not give timestamp correctly for...
   + split_ident_line(): make best effort when parsing author/committer line

--Characters and Letters--
* jc/maint-ident-missing-human-name
"git show --format='%ci'" did not give timestamp correctly for...
 + split_ident_line(): make best effort when parsing author/committer line

--Characters and Spaces--
* jc/maint-ident-missing-human-name
  "git show --format='%ci'" did not give timestamp correctly for
   + split_ident_line(): make best effort when parsing author/committer line

My preference would be first for letters and spaces, or if that is not good enough then characters and spaces.

With regards to the comment that the old header line appears in the middle of the output, as I said earlier that was a consequence of reordering and indenting everything but otherwise leaving it as is. This should be changed, so how about:

<branch-name> (<creation-date>)
  <branch-description?>
  <notes-and-memoranda?>
  <next-steps?>

  <#-commits> (<merge-status?>)
   [list-of-commits]
  (<branch-usage?>)

eg:
jc/maint-ident-missing-human-name (2012-08-31)
  "git show --format='%ci'" did not give timestamp correctly for
  commits created without human readable name on "committer" line.

  1 commit (merged to 'next' on 2012-09-07 at 0e99b20)
   + split_ident_line(): make best effort when parsing author/committer line

with no description:
sl/autoconf (2012-09-11)
  2 commits
   - build: don't duplicate substitution of make variables
   - build: improve GIT_CONF_SUBST signature

Hopefully that makes more sense and addresses the concerns you raised. Adding an asterisk at the start is ok by me, if that is something you think is needed.

One thing I did think about, when leaving the asterisk in the middle of the listing in the first version, was how machine readable the format was. I'm not sure if that is important, but the asterisk was a clear signal that what followed was a listing of commits. In any case, the new and revised format is perhaps slightly less machine readable as a result.

I feel a little bit like I might be bikeshedding this, however I do think an improvement to the formatting of "What's cooking" is a meaningful one for the project!

Regards,

Andrew Ardill