Talk:Development Guidelines: Difference between revisions

From coreboot
Jump to navigation Jump to search
No edit summary
 
(Proposed commit message policy)
Line 2: Line 2:


* http://www.freebsd.org/doc/en_US.ISO8859-1/articles/committers-guide/rules.html
* http://www.freebsd.org/doc/en_US.ISO8859-1/articles/committers-guide/rules.html
== Commit messages ==
=== Short Summary ===
Try to encapsulate what the changeset effects in the source tree at the begining of the commit message. For examples:
mainboard/amd/foo: ..
superio/bar: ..
and so on. The short summary should be 50 chars or less.
=== Body Text ===
* Try to explain the reasoning behind your changeset, not how you did it or what tools you used.
* Avoid putting URL's in commit messages. URL's do not last forever.
* Do not put shell script in commit messages please.
Additionally, putting executable shell script and URL's in commit messages makes it harder to match & parse useful information out of the commit message body with standard unix tools (awk,grep,sed,..).
It is also not directly useful in figuring out what your changeset is actually about while looking back.
To cross reference your changeset with a older changeset in git's history, use its short hash set to 7 chars like in the following example:
Following the reasoning in,
  e2f3bfc jetway/nf81-t56n-lf: Use std memset/memcpy func over AGESA
This is good practice as one can use standard *nix tools to parse out this information depending on what they intend to do..
Here are some examples to demonstrate the point of this rational:
Make a patch since that referenced commit hash in the commit hash 'ac6b7ab',
git format-patch $(git log -1 --pretty=format:%b ac6b7ab  | grep -E "\b[0-9a-f]{7,40}\b" | awk '{ printf $1}')
Or show its summary,
git show --pretty=medium --summary --color=always $(git log -1 --pretty=format:%b ac6b7ab  | grep -E "\b[0-9a-f]{7,40}\b" | awk '{ printf $1}')
Or you can even pass it to git-bisect to bisect from the embedded reference.

Revision as of 19:06, 1 May 2014

Some other interesting commit rules can be found here:

Commit messages

Short Summary

Try to encapsulate what the changeset effects in the source tree at the begining of the commit message. For examples:

mainboard/amd/foo: ..
superio/bar: ..

and so on. The short summary should be 50 chars or less.

Body Text

  • Try to explain the reasoning behind your changeset, not how you did it or what tools you used.
  • Avoid putting URL's in commit messages. URL's do not last forever.
  • Do not put shell script in commit messages please.

Additionally, putting executable shell script and URL's in commit messages makes it harder to match & parse useful information out of the commit message body with standard unix tools (awk,grep,sed,..). It is also not directly useful in figuring out what your changeset is actually about while looking back.

To cross reference your changeset with a older changeset in git's history, use its short hash set to 7 chars like in the following example:

Following the reasoning in,
 e2f3bfc jetway/nf81-t56n-lf: Use std memset/memcpy func over AGESA

This is good practice as one can use standard *nix tools to parse out this information depending on what they intend to do.. Here are some examples to demonstrate the point of this rational:

Make a patch since that referenced commit hash in the commit hash 'ac6b7ab',

git format-patch $(git log -1 --pretty=format:%b ac6b7ab  | grep -E "\b[0-9a-f]{7,40}\b" | awk '{ printf $1}')

Or show its summary,

git show --pretty=medium --summary --color=always $(git log -1 --pretty=format:%b ac6b7ab  | grep -E "\b[0-9a-f]{7,40}\b" | awk '{ printf $1}')

Or you can even pass it to git-bisect to bisect from the embedded reference.