Tracking configuration changes

Drupal 8's new Configuration Management system can be used without a version control system, but if you want to really improve your process, you should use it in combination with version control. Having organized and versioned code helps prevent mistakes and duplicated efforts between multiple developers; it serves as documentation of the project's history and can show who worked on what and, very importantly, why.

There are others, but we are going to talk about Git as our example version control tool because it's used by the Drupal community and offers everything we need in terms of functionality, scalability, and ease-of-use.

Note

Use a version control tool such as Git to get the best out of the Configuration Management system!

The best time to start with versioned Configuration Management is at the beginning of the development. However, it's never too late, even if your project has been started or even finished for a while. Check your Drupal site configuration, organize it, and put everything in a Git repository. Now, you have a good starting point from which to manage and document any changes that will be made to the project in the future.

Some version control best practices

So let's see what will really improve the development process when using version control.

Using a project management tool

You will achieve the best results if you put your work tasks in a project management tool such as the free and open source tool Redmine. If you're not used to working with a project management tool, it might take some discipline to keep track of your work this way, but it has so many advantages. The ticket holds information about what needs to be done and you can use the ticket's comments to discuss requirements, give status updates, or report problems.

Most project management tools also have some sort of ID for each ticket. You can use the ticket ID in your Git commit messages, which is a very good way to know why a commit was made.

Meaningful commit messages

Commit messages are a very important part of your code documentation when working with version control. When looking for something that was done in the past, you will first scan through the commit messages, as shown in the following screenshot:

It makes no sense at all to just use a commit message such as stuff or even asdf. You might laugh, but we've seen both of these in real-world projects. When you start out with version control, it will take some discipline to write meaningful commit messages, but it's really worth it when you come across a bug and are looking for code that might have caused it. Make sure you always use the ticket ID that your project management tool provides and put it at the beginning of your commit message. When you find the commit that causes the problem, the ID will give you more information about what was done there and for what reason.

Note

Small and well-structured commits are more effective.

Also, make commits small! Do not wait until your workday is over to commit everything you did on that day. This will make it more difficult to go through the changes in that specific commit. For example, make each new contributed module you add to your project a separate commit; do not add 5 modules at once or a module together with other code or configuration.

Meaningful branches

Tickets that require a lot of work should be worked on in a separate branch. When you name that branch, make sure you use your ticket ID at the beginning—for instance, 1234-publications, as shown in the following screenshot: