Put EVERYTHING in version control!

The whole software world is backed by Version Control Systems, providing history and traceability to code changes. But you don’t have to restrict its usage to code. Read on to learn how TOPdesk enjoys the benefits of a VCS by employing it in 5 alternative ways.

1. Documentation:

You want your documentation to live as close as possible to the code it describes. Putting your documentation right next to the code in a VCS allows you to keep both up to date. People who work with a certain revision are automatically presented with the relevant documentation for that version.

We also have a repository containing some high level documentation. For example architectural design decisions and other documentation that not necessarily applies to one single software project. It also serves as a hub to connect the live documentation of several software projects together.

2. Our build configurations:

We use Maven as dependency and build management tool. In our pom.xml we have defined what artifacts we want to build, how we want to run our tests and more. We have different Jenkins jobs that run only the unit tests, the integration tests or a full build. Each Jenkins job is configured with the correct Maven commands. The job configurations vary over time when the Maven configuration is updated or build steps are no longer necessary.

To enjoy the same benefits of a VCS, we installed the Job Config History plugin. This plugin allows us to compare and roll back Jenkins job configurations, as well as auditing who changed what. Unfortunately the plugin has no ‘commit message’ option to state why a configuration change is applied.

A newer solution we apply in our most recent Jenkins jobs are the Jenkins Pipelines. A Pipeline is a recipe describing how to build, package and deploy your software project, corresponding to our separate Jenkins job configurations. The Pipeline script is defined using a Groovy DSL. This script can be stored in the configuration of a Jenkins job, giving us version control through the Job Config History plugin. But the script may also be put in a Jenkinsfile in the repository, next to your code. This gives you all the benefits of the VCS your code is in and is very convenient.

3. Our scripts to provision our servers:

We provide TOPdesk optionally as a ‘Software as a Service’ package, where we reduce a customer’s maintenance load by hosting their TOPdesk on our infrastructure. Our Operations team is regularly starting and configuring new servers to scale our SaaS offering. They have created automated installation scripts for each server role in our network. This saves them a lot of work, since a server installation is no longer a manual process of hours of waiting and installing; instead a single command kicks off the entire installation and configuration.

4. Our entire infrastructure configuration:

With our server provisioning scripts in hand, we needed a way to store the desired state of our infrastructure: how many servers in role X running at datacenter Y, connected through network Z. Accountability is very important for these production servers with customer data. Also incidentally a configuration change does not work as expected and it must be reverted. So we chose to store this configuration in a VCS. By requiring that all server management is done through the VCS, our entire infrastructure configuration is traceable, revertable and reproducible.

So we basically treat our infrastructure as code.

5. This blog post:

By treating my blog posts as code, I can have an insight in all my revisions and can recover previously scrapped snippets. I can also make use of the various code review tools, to have my fellow developers review my draft. Also co-writing a blog becomes feasible without having to email BlogPost_WithMyPartAdded_final_v2_really_final.docx around. Microsoft Word documents are not well understood by a VCS, so I need to mark up my blog post using a simple markup language. But we all prefer Markdown, BBCode, HTML and LaTeX above Word don’t we?!