.svg)
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:
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:
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:
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.
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.
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.
If you have any questions or need help with implementing version control at your lab, contact us.
