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.
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.
Set cache headers
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