Go to the profile of Jakub Kułak
Jakub Kułak
Looking for challenges in MX DF. Developer, manager, team player and a gamer. Resume: https://www.linkedin.com/in/jakubkulak

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.

It seems like a must in our system, deploying to production…
  • 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 the message 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 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 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)

Further reading

Many great and inspiring articles have been written about great commit messages and working with GIT/SVN 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 :)

Happy contributing!