Best Practices in Agile for Source Control

Version control (also known as source control) is not strictly an Agile “practice”. However, Agile is proponent for good Source Code practices and has gain widespread support in the industry. Here are some reasons why:

  • It helps mitigates risks for broken, buggy code.
  • Source Control is not merely “good practice” but an enabler of a number of Agile practices, such as continuous integration.
  • The Agile community leans toward particular types of tools and practices, like the Open Source community: systems that afford concurrent work (“merge” model rather than “lock”), and more recently favoring distributed over centralized models – makes coding more efficient.

It is therefore beneficial for Agile teams to explicitly reflect on its version control policies and infrastructure, and ensure that they and its engineering practices work harmoniously together.

Here is our list for Source Control best practices:

#1: If it’s not in source control, it doesn’t exist!

  • Code sitting on your machine is of no value to anyone else.
  • Code sitting on your machine can be lost.
  • It is typically recommended to always push your code before the end of your work day.

#2: Commit often

  • A commit, or “revision”, is an individual change to a file (or set of files).
  • Commits should be a logical – usually small – grouping of changes.
  • Every commit is ideally a viable rollback position.
  1. With a good branching strategy, this is less important as each branch creates an ideal rollback position.
  • Frequent commits keeps merges small and manageable.

#3: Verify your changes before committing

  • Use a different tool to inspect all your changes to make sure you are only committing what you intend.
  • Verifying your changes before committing also helps to avoid accidentally checking in changes you meant to revert.

#4: Build and test before every commit

  • It should be reasonably safe to rollback to any commit, so ensure it builds and tests pass.
  • Thus a commit should not have code in an incomplete state.
  • While unit tests should be run constantly, you should only need to run integration / end-to-end tests before a push.

#5: Branch

  • Most features – or important bug fixes – should be their own branch. However, try to not have too many Branches.
  • You should NEVER work on the default / head / master branch.
  • Branching isolates and insulates your work into clean, manageable sections.

#6: Commit messages are your friend

  • Always describe in detail what changes you have made in a commit.
  • Prefix every commit with a reference to the story / bug ID.
  • Commit messages allow everyone to see at a glance what work has been done, and is invaluable for historical lookups.

#7: Do not commit generated artifacts

  • Generated artifacts such as: generated classes, generated docs, compilation output, etc.
  • Use an ignore file to ensure that these files are not included.

#8: Do commit dependencies where applicable*

  • Other developers should not have to manually install dependencies to get your code to run.
  • The build machine also needs access to the dependencies.

*Unless your system uses a dependency management system (such as Maven or Bower).

#9: Version your database

  • Whatever commit someone is at, their database should be in sync with those code changes.
  1. e.g. The code you pull references a new column in the database; this code will fail if the database schema hasn’t been updated with that new column.
  • Automate revisions, “revision” table to track DB state, etc.

#10: Source control is your safety net. Use it!

  • You always have a place to revert to, so don’t be afraid to play around with an idea.
  • You always have the code history so never comment out code you don’t need – just delete it.
  • Always use the repository tools for moving/renaming/etc.; otherwise, you risk losing the history.