Re: branch description as a note?

Konstantin Ryabitsev <konstantin@linuxfoundation.org> writes:

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.