5. Version control and deployments

Source code has to be stored using a version control system (VCS) so that changes can be tracked over time.

It provides the ability to:

revert to an earlier version whenever you want to
record your changes and the reasons why you made them, to help future developers understand the process
work on changes in parallel as a team before merging them together

Git is the recommended VCS. This is supported by MAMPU’s guidance on version control here. In the unlikely event there is a requirement to deviate from this standard please discuss with the project owner.

5.1 Making Commits

Making a commit means making a set of changes permanent. You should:

write clear commit messages
group changes according to their purpose
review new changes

5.1.1 Commit Messages

Writing good commit messages is important. Not just for yourself, but for other developers on your project. This includes:

new (or recently absent) developers who want to get up to speed on progress
interested external parties who want to follow progress of the project
people in the public (remember, we code in the open) who want to see our work, or learn from our practices
any future developers (including yourself) who want to see why a change was made

Capturing context around a change allows people to understand why a particular implementation decision was made, much like an architecture decision record. We’re being kinder to our future selves.

Content

A good commit message briefly summarises the “what” for scanning purposes, but also includes the “why”. If the “what” in the message is not enough, the diff is there as a fallback. This is not true for the “why” of a change - this can be much harder or impossible to reconstruct, but is often of great significance.

Example

Set cache headers

prefer:

Set cache headers

IE 6 was doing foo, so we need to do X. See http://example.com/why-is-this-broken for more details.

5.2 Things to keep out of version control

Sensitive information should not be kept in the version control system. These should be provided by the environment which the system is run on, eg. environment variables, secret stores.

Some examples of sensitive information: