Konstantin Ryabitsev <konstantin@xxxxxxxxxxxxxxxxxxx> 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.
