VCS Best Practices

From Gcube Wiki
Jump to: navigation, search



General rules about messages in the Version Control System:

  • Each commit MUST have an appropriate comment.
  • Use the comment to explain what and why, NOT how
  • Capitalize the first character of the comment
  • End the comment with a period
  • Use the imperative mood in the comment
  • Limit the comment to 2 or 3 sentences.

How to commit

General rules about commits in the Version Control System:

  • Each commit MUST be as self-contained as possible. A commit can be potentially be cherry picked by any branch to apply its change to the target branch.

How to NOT commit

Some rules to avoid bad practices in the usage of the Version Control System:

  • VCS is not a backup system! Developers who use it as such tend to do end-of-day commits, checking in everything at the end of the day. The result is useless, a random diff across the code with changes that are impossible to understand by anyone including the original author once a few months have passed.
  • Avoid lazy commit messages, any commit labelled as "misc fixes and cleanups" or similar. Messages must be meaningful.
  • Avoid whitespace/formatting/cosmetic changes together with code changes in the same commit.
  • Never save two unrelated changes in one commit. Something like "Fixed bug 2345 and renamed all foo to bar". Unless bug 2345 required the renaming, fixes would be split it up into multiple commits.

Back to the CI guide.