Re: branch description as a note?

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

Konstantin Ryabitsev <konstantin@linuxfoundation.org> writes:

>> If this is about draft work, I would use an empty commit at the tip
>> of the branch.
>
> I think this was discussed a while back:
> https://lore.kernel.org/git/xmqqilnr1hff.fsf@gitster.g/
>
> I think it boiled down to having a merge commit at the tip that would indicate
> the base-commit of the WIP range. I still think it's an awesome idea if
> something like this was natively supported by git tools.

I suspect taht Bence misunderstood some assumptions behind the above
discussion, some of which might not match the use case he has with
his "branch descriptions".

So, forgetting Bence's "branch description" for a while, let's see
if we can summarize the assumptions the older discussion had.

 1. We want to summarize what is on the branch, to help the reviewers
    and also the original developers.

 2. When the branch gets accepted to another branch that is higher
    in the food chain (e.g., an individual developer has a topic to
    improve a kernel driver for one specific hardware, the developer
    describes what they did and give the branch to the driver
    maintainer, and the topic gets merged to the driver's tree. The
    resulting merge may not yet be in Linus's tree, but from the
    original developer's point of view, the topic is "done" for
    now), a merge commit will use the "summary" created above in the
    messages of the merge commit.

 3. Once that happens, as it is etched into the merge commit, you
    cannot update the description anymore (unless you and your
    maintainer arrange to discard the merge and take an updated
    branch), and that limitation is acceptable.

The idea to use an empty commit is to make it easier to communicate
the "topic description" between the author and the maintainer.
During the development on the branch, the empty-commit that holds
the description can be updated using the common "rebase -i"
workflow.  If the empty commit were at the tip of the branch[*], we
can teach "git merge B" (or "git pull") to notice that the topic
description is in the commit B at the tip of the branch, create a
merge with B~1 instead, and when recording the merge, offer the log
message of B to help the maintainer write the log message for the
merge commit.  The e-mail based tools would need some changes (like
allowing "format-patch | am" pipeline to pass an empty commit), but
the principle is the same.

If Bence's "branch description" is for a use case where the
description need to be updated even after the branch gets
"concluded" by being merged to the upstream, that is not a use case
the topic description stored in an empty commit on branch we
discussed earlier would cover, I suspect, as the primary focus is to
make it easier to maintain in point 1. above, and finalize it in the
merge commit to describe what was merged in point 2. above.


[Footnote]

 * IIRC, there were some who preferred to make the description empty
   commit at the bottom of the series, and while it is possible to
   arrange such layout, it makes the eventual "git merge B" a lot
   more cumbersome (i.e. you'd need to rebase B onto the
   maintainer's tree, except for the bottom of the branch, and use
   the message from the now-discarded commit for the log message of
   the merge commit), and it would force developer to rebase the
   _entire_ branch every time they need to update the description.
   So I strongly prefer "description at the tip" layout, but the
   choice between bottom and tip does not affect the 3-point
   assumptions above.