Hi Everyone,
I¹d like to open up a discussion around the gem5 commit message style
guide. In particular, I¹d like to make life better for users of git-baesd
tools, improve tracking, and acknowledge reviewers.
The current style guide[1] mandates this:
* The first line of a commit message is a summary line
* Subsequent lines provide a detailed description
* The summary line starts with a series of keywords separated by commas
followed by a colon and a short patch description.
* The summary line can¹t be longer than 65 characters.
* The detailed description is wrapped to fit in 80 columns.
I would propose to make three changes:
1. Limit detailed lines to 75 characters
A lot of tools (especially git-based tools) nowadays seem to assume that
the detailed description is wrapped at 75 characters or less. The Git Book
and GitHub suggest ³72 characters or so² [2, 4], Linux mandates ³70-75
characters² [3]. I¹d suggest that that we limit summary lines to 75
characters. This is in practice the upper limit imposed by the kernel and
would work nicely with the way git indents log lines.
2. Add a blank line between the summary line and the detailed description
This seems to be suggested by Linux, GitHub and the Git Book.
3. Additional tracking and acknowledgements
A long-term change that I¹d like to see is adding more tracking to commit
messages. In particular, I would like to introduce these tags (see [3] for
a description of how they are used in Linux):
* Reviewed-by: This would be used to acknowledge the work of reviewers.
We already use this internally and that have gone through internal review
within ARM will have these tags.
* Signed-off-by: This tag tells other developers that the patch author
has the right to submit this work. Similarly, people in the delivery path
of a path add a this tag to say to indicate that they have received it in
good faith and forwarded it. See [5] for a description of how the kernel
uses it. Any modifications (rebasing) would be described within brackets.
For example:
Signed-off-by: Foo Bar <. . .>
[Rebased to work with latest gem5]
Signed-off-by: Andreas Sandberg <. . .>
Another good example would be the fork patches [6]. These were written by
me before I joined ARM, rebased by Sascha Bischoff, and finally pushed by
me.
Cheers,
Andreas
[1] http://www.gem5.org/Submitting_Contributions
[2] https://git-scm.com/book/ch5-2.html
[3]
http://lxr.free-electrons.com/source/Documentation/SubmittingPatches#L600
[4] https://github.com/blog/926-shiny-new-commit-styles
[5]
http://lxr.free-electrons.com/source/Documentation/SubmittingPatches#L409
[6]
https://github.com/gem5/gem5/commit/738d71f6a93e2da9ef5bb1490f2b94f9541735e
3
IMPORTANT NOTICE: The contents of this email and any attachments are
confidential and may also be privileged. If you are not the intended recipient,
please notify the sender immediately and do not disclose the contents to any
other person, use it for any purpose, or store or copy the information in any
medium. Thank you.
_______________________________________________
gem5-dev mailing list
[email protected]
http://m5sim.org/mailman/listinfo/gem5-dev
