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:

  • API Keys
  • Username & Passwords
  • Database connection strings

Improving The Page

The standards on this site has been developed to provide guidance for those within the government or those doing related projects with the government. Adoption of the standard will ensure a minimum level of quality is present in all of the projects and systems. To further improve the standards, regular feedback is required to ensure it is relevant and provides value to the current and future environment.

Your opinion matters. Click "FEEDBACK" to let us know how we can further improve the standards.

Is this page useful?