Source control: best practices Agile by Intelliware

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

Best Practice #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.

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

  • 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

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

  • 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

  • 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

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

Other developers should not have to manually install dependencies to get your code to run.

The build machine also needs access to the dependencies .

Best Practice #9: Version your database

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

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