Extend DevOps with specifications documents and automate as much as we can.
- Keep the specifications documents and code synchronised
- Create close-out references1 that get invalidated as soon as the requirements change.
- Automate the generation of documents2
- Always up-to-date documents
- Document versioning is supported with git tags
- Fail the CI-pipeline if requirements change
And some things that should not have been forgotten were lost. History became legend. Legend became myth. And for two and a half decades, the paper passed out of all knowledge. - Galadriel, CTO Lothlórien
Because the frozen waterfall didn’t deliver (obviously), there was a counter-revolution: Agile with the following four bullet-points:
- Individuals and interactions over processes and tools
- Working software over comprehensive documentation
- Customer collaboration over contract negotiation
- Responding to change over following a plan
Fast feature-implementation required quick delivery to customer. Hence the deployment had to be automated, which means even more code. Who writes the code? The developer and DevOps was born.
Deployment straight out of your CI pipline: continuous delivery (CD).
Point two above guarantees that there was no documentation for the customer.
Security is important. Who would’ve thought? And still no documentation for managers.
It seems that SAFe is now the standard for doing agile. Even in its smallest version (Essential) there’s a product manager whose role is, among others, to provide requirements for the project.
At this point it boils down to writing down what’s been said in point 2 and verify it through testing. Because testing wants everything in its CI-pipeline before pushing to production, we also need to verify against the requirements and fail the build if upstream requirements have changed without affecting the code.
For free we get the documents managers can read and understand, i.e. not code.
A solution is proposed to keep requirements and the other deliverables in sync. For this all requirements documents have to be added to the CI/CD pipeline.
Close-out references1 to requirements, e.g., test specifications, contain a
reference to the requirement’s ID, e.g.,
To propagate changes in requirements downstream, a hash is calculated over
the relevant part of the requirements. These are then added to the close-out
reference. This modifies the previous reference to, e.g.,
In the following image a reference specification item is shown.
The item’s identifier is given next to the title. The hash calculated over the title, description and identifier.
def test_read_write_engines(record_property, dummy_vcd_file): """Write-back from read file, equal output""" record_property('req', 'SW-AS-501-f8d68d11') record_property('req', 'SW-AS-500-4c1a395a') ofile = 'test_writeback.vcd' reader = pymergevcd.vcd_reader.factory(dummy_vcd_file) writer = pymergevcd.vcd_writer.factory(ofile) writer.process_source(reader) assert filecmp.cmp(dummy_vcd_file, ofile)
The previously defined
record_property results in the following entry in the
xunit XML results file
<testcase classname="tests.test_io_manager" file="tests/test_io_manager.py" line="20" name="test_read_write_engines" time="2.830"> <properties> <property name="req" value="SW-AS-501-f8d68d11"/> <property name="req" value="SW-AS-500-4c1a395a"/> </properties> </testcase>
result.xml file is then used to derive the traceability matrix.
The previous examples have been taken from the reference implementation. The
pymergevcd project also serves as a reference
Download the ZIP file and run the
./run-docker.sh if Docker is installed). Without Docker, a working
Python 3 installation is required. This generates the documents in the
artifacts/ directory, especially the
The generated spreadsheet can be distributed to stakeholders to be modified. If
it’s copied to the
imports folder, the changes will be incorporated with the
- show example of adding it to CI pipeline
- maybe run it in gitlab?
The main point of CI/CD is to unambigouosly document the processes to compile, test and ship software. ↩
Please don’t do this ↩