Re: branch description as a note?
On Thu, Dec 12, 2024 at 10:39:37AM +0900, Junio C Hamano wrote:
Show 5 quoted lines
> 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.
Plus keep track of the history of the branch evolution (such as changelog between different submissions).
Show 9 quoted lines
> 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.
Correct, though this is a very Linux-specific example. Some of the other projects have specific workflows restrictions that require that all commits are linear (e.g. glibc/gcc) -- using merge commits wouldn't be suitable to them. However, I think they are outliers in this regard.
> 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.
Correct. Normally, once the maintainer accepts a patch series, no further changes are made to its contents. The pull request set to the maintainer's upstream (=Linus) will be accepted as-is or rejected as a whole, as a general rule.
Show 12 quoted lines
> 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.
Yes, and the commit would have two parents, one pointing at the previous commit and the other pointing at the base commit, which would help the tools identify where the series starts and ends.
Show 22 quoted lines
> 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.
Right, this is what b4 does, but b4's use case is very specific in the sense that the series will almost always be sent out to the list and then applied from there, and never merged directly from the work branch. This *has* happened before, notably, so this assumption does get broken.
Since the series is intended to be sent to the list, the fact that it is continuously rebased doesn't really matter, because the commits themselves are ephemeral and don't mean anything in the long term.
Additionally, keeping the tracking commit at the bottom of the series is just the default strategy. There is also a way to make it live at the tip of the series, but it has its own awkwardness that will almost certainly trip up more newbies. If git does get a native way to use such cover letters, I will certainly switch to that as the default.
-K
Bence Ferdinandy
