Good practices for cooperative work with GIT/SVN (and other version control systems)
Below you will find my selection of good practices for working with version control software, how to fine-tune your source code files, keep your commit history clean, write clear and insightful commit messages.
Formatting — prepare your source code files
Basically — remove any excessive whitespace and empty lines from your files — so that they don’t appear as changes in your code repository never again.
- Remove all trailing whitespace from empty lines
- Merge consecutive empty lines into one
- Make sure last line has an end line character — because every line should have an end line character (so e.g. we don’t see those ugly, red arrow characters in GitHub)
- Best if you make your favourite code editor take care of all those points (check Sublime Text or Atom — they have you covered!)
Writing commit messages — describe your contribution
Commit messages should be descriptive and clear. E.g. in case you need to roll back changes from production quickly — you want to be able to quickly understand up to which commit you want to roll back.
- State clearly what has been changed, start your commit messages with a verb in present tense in an imperative form: Add…, Fix…,
Remove…, Make…, Configure… (messages like “Advertisement code for category pages” — don’t tell us if it was removed, added or modified — so it is useless)
- Make your commit message 50 or less characters long
- Don’t put period at the end (it’s a title and you don’t put periods at the end of the titles)
- If your commit message brings extra “why?” question in mind, add extra details in the commit description, by pointing them out
- You can also point out some technical details in the description if it’s necessary
- If you are working with a ticketing system, add the ticket ID in the beginning of a commit message so it integrates nicely with your software (e.g. Jira, Confluence) — this depends on your organisation — so discuss it internally
And please, don’t use http://whatthecommit.com/ as an inspiration.
Pushing/committing changes — keep your repository (and history) clean
Your cooperation model depends heavily on your organisation, so discuss internally, and don’t apply any guidelines blindly.
- For all changes you want to make, create a separate branch (new feature, bug fix, removing an old feature), read more here: http://nvie.com/posts/a-successful-git-branching-model/ and adjust to your organisation/environment
- Squash excessive commits to keep repository’s history clean (before pushing your branch make sure there are no unnecessary commits like: “Fix the title typo” or “Forgot to add the dependency”). Great tutorial here: http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html
- When working with GitHub (GitLab, etc.), use Pull request or rebase to merge your changes (depending on your working model) into desired branch
- Don’t commit changes not related to you current task/feature (do it rather in a separate branch)
- Don’t commit any debug/test code (var_dump(), console.log(), etc.) — you could automate this, by setting up a pre-commit hook (thanks Julian)
- Stick to coding standards defined for your project… obviously
- Have linting implemented in your workflow (with shared/common configuration among your team)
Many great and inspiring articles have been written about great commit messages and working with code repositories already and they provide much deeper insights and even more guidelines. Below I have listed some of that I liked the most. Applying rules from this article makes you awesome already, but go and read those articles if awesome is not enough for you