On the Semaphore Solutions blog, we’ve talked a lot about the importance of a lab’s software stack and strategies for managing multiple software components — some you’ve bought off-the-shelf, some that are fully custom, and some with varying degrees of customization. But one thing we haven’t dug into is version control. This is a key part of managing any complex software system, so it’s something every lab should understand.
Because laboratory information management systems (LIMS) terminology varies from system to system, to keep things simple, we’ll use the following terms in this post:
- Step. A single process, contained in a single work session, at one physical location.
- Protocol. A collection of steps that facilitate one stage of the workflow.
- Workflow. End-to-end sample processing from accessioning to report issuance.
What is version control?
In the software development world, version control (also known as “source control”) is a method for tracking and managing changes to software code. Version control software — like GitHub (this is the one we use), GitLab, Perforce, Mercurial, and others — uses a database to track every change and who made the change. Check out this video by Atlassian for a quick overview.
Two major benefits of tracking changes are:
- You can compare sets of code (changesets) to troubleshoot any mistakes or conflicts. For example, let’s say 99 lines of code inside the two changesets are the same and one line is different. If this modification causes a problem, we know exactly where to go to investigate the problem because the change has been recorded.
- You can roll back to a previous version of the code if a modification breaks the build. This minimizes disruption to other team members while you fix the mistake.
Why version control is important in the lab
Using version control is good software development practice. But beyond that, it’s necessary for maintaining compliance in a regulated lab environment.
Regulatory bodies, such as the College of American Pathologists (CAP), require evidence that laboratory information systems (LIS) are adequately tested for proper functioning when they are first installed and after any subsequent modifications. Customized software and any modifications to that must also be documented. Plus, you have to track the people responsible for each modification.
Types of modifications include:
- Adding or modifying a script.
- Adding or modifying configuration.
- Upgrading a software version.
If you’re curious about the level of rigor required in documentation, check out this GAMP categorization, which outlines the lengths you have to go to validate a software installation depending on the category your software falls into. Most LIMS are configurable pieces of software, so will fall into GAMP Category 4.
Version control essentially fulfills the record requirements of CAP by tracking modifications to the software code and capturing which users made the changes. That means for each version of the LIMS, you can easily enumerate all the changes that are included.
Which software in the lab needs version control
Labs need to have a good understanding of each piece of software used in the lab so they can anticipate and troubleshoot problems that occur when changes are made. But they should also be aware of which software needs version control.
This differs from lab to lab, depending on a lab’s software stack and infrastructure. For any lab using a LIMS (arguably the most important piece of software in the lab), we recommend using version control for this at the minimum. Also, consider using version control with your instrument and electronic health record (EHR) integrations. Think about what will happen if you upgrade your LIMS version but all the workflows stay the same. In this case, you’ll want to use version control for any middleware (such as HL7 listeners) and infrastructure (data stores and dependencies).
When we work with labs using Clarity LIMS, for example, we start by adding a version number to workflow names. Because we manage changes at the workflow level, if we make a change to any workflow components (such as a script change or change in step configuration), we increment the version number on the workflow. When we make changes, we use the Config Slicer tool to create a configuration manifest file with the updates. We use our Clarity Library to normalize the manifest file to compare it against the configuration in the development environment. Then we import the manifest file into the target environment (Staging, Production, etc). Once that is done, we manually increment the version number of the affected workflows. Finally, and most importantly, we document the changes so that we have a record of what was done in case a reversion is required.
NOTE: If you don’t know about our Clarity Library, we highly recommend you check it out. It’s an extremely useful tool that lets you perform diffs on configuration versions — and it’s open-source, so free to use.
End-to-end version control
As well as using version control for the individual infrastructure components (software, database, other components, and dependencies), we recommend labs apply version control to the entire end-to-end diagnostic assay process.
If the LIMS has no built-in versioning, we suggest you describe the state of each component (workflow, protocol, step, and script) and give that set of changes a version number (or release name). It’s best to use a formal change control process where the state of every component is documented and sign-off is required from internal and external stakeholders. This ensures everyone is aware of the change, when it’s going to happen, and how it’s expected to behave.
When a simple script change is needed, it can be tempting to avoid using the formal change control process. However, we’ve seen this result in a lot of problems. If everyone is not aware of the change, when an issue arises, support staff might be confused by things not working as expected. Our recommendation is to set up a formal version control process — and follow it every time, no matter how small the change.
