Setup standardized git commit template

[kloudkl]

Caffe has seen six hundred forks as of creating this issue. The contributors will no doubt continue to grow and diversify. For they and especially the reviewers to understand each others commits easily even with little knowledge of the initial issues, the commit messages should be much more comprehensive than one-liner commits with empty or almost empty message bodies.

It might be overkill to follow the heavy weight git commit messages guideline of OpenStack which serves to coordinate thousands of contributors from hundreds of organizations. Instead, setting up a relatively light weight commit template would be good balance between the two extreme cases. A simple example is here.

As a consequence of writing more self-contained commit messages, all of the commits of a PR had better be squashed into a single one to keep the one to one relation between commits and PRs and to reduce the writing burden. To automatically create release change logs from the git log, the issue/PR ID should always be set at the end of the commit messages.

[ducha-aiki]

Vote up.

[longjon]

I agree that we should have a better standard (i.e., any standard) for commit messages.

I don't think we need a one-to-one correspondence between commits and PRs; I prefer that each commit be a small, logical, nonbreaking unit. This makes it easier to find bugs (e.g., using git bisect) and easier to understand the history. (As an example, I used nineteen commits in #594, and I think it would be quite hard to follow as a single one!) However, I do support keeping PR history clean by rewriting (e.g., PRs should never have commits to revert changes or fix typos, lint errors, or warnings within the PR; the commits should be rewritten to be right in the first place). The tradeoff is that this puts a higher bar on contributions, since contributors need to be comfortable with rewriting history.

If we are going to make a change to commit policy, I'd also lean in the direction of a soft change, so that we can see how we like it without creating an undue burden on anyone. A lightweight commit template might be a good idea, but I've not used one before, so I'd like to hear some more opinions...

[Yangqing]

A better PR message would definitely help. Personally I won't care too much on individual commit messages - I like commit messages to be fun and I don't mind having a few commits flying around, as long as they are correct in the end.

[shelhamer]

A key part of PR quality is communication. High quality contributions come with thoughtful PR descriptions and commit messages and I'm afraid there's no template for consideration.

I like my commits atomic and echo @longjon's thoughts on the matter. I'm in total disagreement that PRs should be a single commit -- in fact, single commit PRs of any non-trivial change are the most difficult to review.

A PR is ideally one pure thought and the commits carry out the steps to realize it. #594 and other PRs by @longjon and @jeffdonahue are fine examples in this regard.

Closing since we have not come up with a commit template and it is not clear at least to me how it will help. Instead there should be a place in the contributing guide for the details of

I prefer that each commit be a small, logical, nonbreaking unit. This makes it easier to find bugs (e.g., using git bisect) and easier to understand the history. (As an example, I used nineteen commits in #594, and I think it would be quite hard to follow as a single one!) However, I do support keeping PR history clean by rewriting (e.g., PRs should never have commits to revert changes or fix typos, lint errors, or warnings within the PR; the commits should be rewritten to be right in the first place). The tradeoff is that this puts a higher bar on contributions, since contributors need to be comfortable with rewriting history.

although seeing it all at once might be intimidating. Suggestions to improve the developing and contributing guide are definitely welcome.