Skip to contentSkip to conversation

Document from line in patch format

PATCH Pete Zaitcev 3 participants 4 messages Oct 3, 2005 1 message not in the archive

lore
Share & tools
lore
#1 lore raw
In reply to a message not in the archive
Quoted 1 line · Paul Jackson

+ Subject: [PATCH 001/123] [<area>:] <explanation>

An attack of rabid square brackets! :-)

Linus' original e-mail made it quite clear that the area does not need its own brackets, but this detail seems to have been lost.

-- Pete

#2 lore raw
Quoted 2 lines · Peter

Linus' original e-mail made it quite clear that the area does not need its own brackets, but this detail seems to have been lost.

I missed that part in Linus's original email. I kinda thought the second set of square brackets was ugly, but who was I to criticize the Master's aesthetic sense <grin>?

I'll go back now and reread that email.

I sense PATCHv5 coming on, soon.

Thanks for catching this.

Signature · 3 lines
                  I won't rest till it's the best ...
                  Programmer, Linux Scalability
                  Paul Jackson <[email protected]> 1.925.600.0401
#3 lore raw
Quoted 1 line

+ Subject: [PATCH 001/123] [<area>:] <explanation>

What's funny is that the first pair is literal and the second one is syntactic. Perhaps you may want to do an EBNF ;-)?

SUBJECT ::= "Subject: [PATCH" NUMBER "/" NUMBER "]" [ AREA ":" ] EXPLANATION

Although the current explanation tells careful readers that "From: " in the body is optional, by mentioning what happens if it is not found, I think it is clearer if you said it upfront.

Maybe something along the lines of:

The body of the message should be structured as follows.

- an optional in-body "From: " line (plus an empty line for readability), if the author is different from the e-mail patch forwarder/sender; followed by

- the explanation to be recorded as the commit log message; followed by

- an empty line, and signed-off-by lines; followed by

- mandatory three-dash '---' line; followed by

- optional non-diff metainformation -- justification message to the maintainer, diffstat etc.

- actual patch material.

I do not know if Linus wants to advertise this, but in addition to the in-body "From: ", the e-mail patch application tool from GIT also understands in-body "Date: ", if the patch forwarder wants to preserve original authorship datestamp in the commit the maintainer eventually makes out of your e-mail. Without it, the "Date: " of the forwarder's e-mail is used as the authorship datestamp.

#4 lore raw
Quoted 1 line · Junio

Perhaps you may want to do an EBNF ;-)?

Hopefully not required here.

See my subsequent patch - I think it is simple and clear:

[PATCH] Document patch subject line better

I started a new patch series, since Linus had already picked up my prior changes.

Signature · 3 lines
                  I won't rest till it's the best ...
                  Programmer, Linux Scalability
                  Paul Jackson <[email protected]> 1.925.600.0401