Linus Torvalds [off-list ref] writes:
The basic issue is how to sanely keep track of a cover letter when you
have a branch that you haven't sent out yet, but will ask somebody to
pull. It may still be seeing more testing and development before that
pull happens, though.
This very much smells of what the "branch description" is all about, but
(a) I suspect "git branch --edit-description" is not very well known
True.
(b) it works well with "git request-pull", but not so much some other
things (like copying it into a signed tag)
I think that is just a matter of programming ;-)
(c) it makes an unholy mess of your config file if you actually use
it for extensive explanations (branch descriptions _work_ for
multi-line messages, but it really was designed as a one-liner thing).
Not, really.
The "-m" option similar to "commit/tag" is deliberately omitted and
use of editor is forced, to encourage better than one-liner
information. cf. b7200e83 (branch: teach --edit-description option,
2011-09-20).
The unholy mess is true if you are in the habit of editing .git/config
in your editor, but that is to be expected if you are storing multi
paragraph description as a value of a configuration variable.
(d) it doesn't work across repositories (ie multiple developers or
even just a single developer on multiple machines).
This is the biggest issue.
IOW, the "branch description" is _kind_ of the right thing, but not really.
Having said all that, quite honestly, as the inventor of the
"--edit-description", I did it as sort of a joke, and not a serious
"feature".
An empty commit would do it as well, but an empty commit very easily
gets lost (git rebase etc). The fake merge does have similar issues.
These days, I think rebase distinguishes between "an empty commit
that is deliberately empty from the beginning" and "a commit that
was not empty, but because we are applying on a new base, it has
become unnecessary and empty", and we can tell the command to drop
the latter while keeping the former. So if I were to design a
recommended workflow (and add any missing workflow elements), it
would be:
- You develop your N-patch series on a branch;
- You conclude with an empty commit that records your cover letter
material.
- "git commit" may want to learn a new option that automatically
prepares summary of the last N patches in the commit log
editor, and the option should imply the "--allow-empty" option.
That would help when editing such an empty commit that will
become the cover letter.
- You repeatedly "rebase -i", "cherry-pick", etc. to whip your
branch into shape.
- You can push and fetch such a branch among your machines and your
group.
- "git format-patch" may want to recognize that the topmost commit
is an empty commit, and use that as the seed material for the
cover letter.
- If your project's pull request requires a signed tag with cover
letter material, "git tag -s" may want to learn a new option to
be fed such a branch with N-patch plus the topmost empty commit,
and tag the last real commit in the topic (i.e. the parent of the
topmost empty commit) with material taken from the topmost empty
commit.
Both a fake merge, and an empty commit have the advantage that they
are easy to see and work with (ie "git log" and all the other git
workflows work very naturally).
Comments from git people?
Linus
I can see how the above outline would work. I do not know if it
would work well for your project, or there are other workflows for
which the above outline would be insufficient.
On Sat, Nov 13 2021, Junio C Hamano wrote:
Linus Torvalds [off-list ref] writes:
quoted
The basic issue is how to sanely keep track of a cover letter when you
have a branch that you haven't sent out yet, but will ask somebody to
pull. It may still be seeing more testing and development before that
pull happens, though.
This very much smells of what the "branch description" is all about, but
(a) I suspect "git branch --edit-description" is not very well known
True.
quoted
(b) it works well with "git request-pull", but not so much some other
things (like copying it into a signed tag)
I think that is just a matter of programming ;-)
quoted
(c) it makes an unholy mess of your config file if you actually use
it for extensive explanations (branch descriptions _work_ for
multi-line messages, but it really was designed as a one-liner thing).
Not, really.
The "-m" option similar to "commit/tag" is deliberately omitted and
use of editor is forced, to encourage better than one-liner
information. cf. b7200e83 (branch: teach --edit-description option,
2011-09-20).
The unholy mess is true if you are in the habit of editing .git/config
in your editor, but that is to be expected if you are storing multi
paragraph description as a value of a configuration variable.
quoted
(d) it doesn't work across repositories (ie multiple developers or
even just a single developer on multiple machines).
This is the biggest issue.
quoted
IOW, the "branch description" is _kind_ of the right thing, but not really.
Having said all that, quite honestly, as the inventor of the
"--edit-description", I did it as sort of a joke, and not a serious
"feature".
quoted
An empty commit would do it as well, but an empty commit very easily
gets lost (git rebase etc). The fake merge does have similar issues.
These days, I think rebase distinguishes between "an empty commit
that is deliberately empty from the beginning" and "a commit that
was not empty, but because we are applying on a new base, it has
become unnecessary and empty", and we can tell the command to drop
the latter while keeping the former. So if I were to design a
recommended workflow (and add any missing workflow elements), it
would be:
- You develop your N-patch series on a branch;
- You conclude with an empty commit that records your cover letter
material.
- "git commit" may want to learn a new option that automatically
prepares summary of the last N patches in the commit log
editor, and the option should imply the "--allow-empty" option.
That would help when editing such an empty commit that will
become the cover letter.
- You repeatedly "rebase -i", "cherry-pick", etc. to whip your
branch into shape.
- You can push and fetch such a branch among your machines and your
group.
- "git format-patch" may want to recognize that the topmost commit
is an empty commit, and use that as the seed material for the
cover letter.
- If your project's pull request requires a signed tag with cover
letter material, "git tag -s" may want to learn a new option to
be fed such a branch with N-patch plus the topmost empty commit,
and tag the last real commit in the topic (i.e. the parent of the
topmost empty commit) with material taken from the topmost empty
commit.
quoted
Both a fake merge, and an empty commit have the advantage that they
are easy to see and work with (ie "git log" and all the other git
workflows work very naturally).
Comments from git people?
Linus
I can see how the above outline would work. I do not know if it
would work well for your project, or there are other workflows for
which the above outline would be insufficient.
There's a more general question to be considered here which is how the
object model is supposed to keep track of this sort of thing, if at all.
One solution is (dare I say?) "git notes". I.e. if you're keeping a
notes/CL about a set of commits you could publish a notes branch where
the CL is by convention on the tip of that commit. Now when someone else
"takes over" your branch they'll "git fetch" your notes, have set up
approprite core.{notes,display}Ref, copy your notes into their own note,
then edit/amend/publish/push.
Setting that up should be small matter of scripting around existing
commands, and should be an improvement on having to manually share or
extract what's now stored in branch descriptions.
On the other hand that information is rather unwieldy to deal with, and
"notes" support isn't very widespread on e.g. git hosting sites
(althougt that's also a chicken & egg problem).
Another solution that fits nicely into the data model is to consider
this the same "problem" as PGP signed commits. I.e. an an
"x-metadata-cover-letter" header could be added to the tip commit object
itself, either an --allow-empty --allow-empty-message commit, or "git
merge --no-ff" in case the range that CL covers is ambiguous (which in
that case would start with the merge base of the two parents).
If git's going to have some native-ish solution to this problem it
should also be considered that what E-Mail based workflows want to do
with CL's is analogous to what popular hosting sites are doing with the
text field for a PR/MR. I.e. ideally such a cover letter could be
stored/structured in such a way that if you pushed a branch to open such
a PR/MR the "cover letter" could be extracted.
Which also gets into questions of if that data should be stored
permanently. I.e. it's a merge commit as described above would the
person merging it expect to merge down the parent (i.e. sans
coverletter), or if it's stored in the commit object rewrite the commit?
And for some text-only cover letters might suffice, but git users in
general observably upload attachments to explain their commits (say a
screenshot of performance numbers). So a design that combined the above
with the ability to point at a tree might be preferred.