Source Control: Best Practices in Agile

Source Control Image for WebpageAs the Agile Alliance states, “Version control (also known as source control) is not strictly speaking an Agile “practice”, insofar as it is now (fortunately) widespread in the industry as a whole. It must however be mentioned…for several reasons:

  • Though they are rare, one still occasionally stumbles across teams with outdated version control tools or practices, and even teams who haven’t adopted version control tools at all
  • Version 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, namely the same as the Open Source community: systems that afford concurrent work (“merge” model rather than “lock”), and more recently favoring distributed over centralized models
  • It is therefore beneficial for an Agile team to explicitly reflect on its version control policies and infrastructure, and ensure that they and its engineering practices work harmoniously together

Here are our top 10 best practices for Source Control.

Download PDF

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

Source Control 2

  • 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.
Best Practice #2: Commit often

Source Control 3

  • 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.
    • With a good branching strategy, this is less important as each branch creates an ideal rollback position.
  • Frequent commits keeps merges small and manageable .
Best Practice #3: Verify your changes before committing

Source Control 4

  • 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.
Best Practice #4: Build and test before every commit

Source Control 11

  • 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.
Best Practice #5: Branch.. Branch.. Branch..

Source Control 5

  • Most features – or important bug fixes – should be their own branch.
  • You should NEVER work on the default / head / master branch.
  • Branching isolates and insulates your work into clean, manageable sections.
Best Practice #6: Commit messages are your friend

Source Control 6

  • 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.
Best Practice #7: Do not commit generated artifacts

Source Control 7

  • Generated artifacts such as: generated classes, generated docs, compilation output, etc.
  • Use an ignore file to ensure that these files are not included.
Best Practice #8: Do commit dependencies where applicable*

Source Control 8

  • 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 ) .

Best Practice #9: Version your database

Source Control 9

  • Whatever commit someone is at, their database should be in sync with those code changes.
    • 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 .
Best Practice #10: Source control is your safety net. Use it!

Source Control 10

  • 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.