14 December 2023 by Phillip Johnston
Embedded Artistry projects use git annotated tags to indicate the status of versioned software builds. The following guidelines will improve auditability and traceability for software builds.
There are four distinct categories of tag messages that apply to versioned builds:
- In-process Tag
- Release Candidate Tag
- Approved Release Tag
- Special Purpose Tag
In-process Tag
The In-process Tag is generated by the Jenkins build server at the start of a clean versioned build. This tag is never to be pushed to the git server; instead, the tag is deleted at the end of the build process in all cases. Public tags matching the In-process Tag format indicate an error with the build process.
The In-process Tag message takes the following form:
git tag -a '${version}' -m 'Creating tag to build ${version}'
Release Candidate Tag
The Release Candidate Tag is used to mark passing clean versioned builds. This tag is pushed to the git server at the end of a successful build.
The Release Candidate Tag message takes the following form:
git tag -a '${version}' -m 'Successful CV build ${version}'
Approved Release Tag
The Approved Release Tag is used when a Release Candidate successfully passes acceptance testing for projects where such procceses are used. The corresponding version tag should be updated to indicate release approval.
The Approved Release Tag message should take the following form:
git tag -a '${version}' -m 'Customer Release ${version}'
Special Purpose Tag
A Special Purpose Tag is any tag which accomplishes a purpose not described above. Such tags must have an annotated tag message which is differentiated from the other forms. The Special Purpose Tag message should include the motivation for the tag and the expected tag lifetime.
A recent experience drove this point home for me: insufficient documentation wastes everyone's time. In Adding Delimiters Between String Elements in C++, I described the creation of a "convenience function" that would simplify the use of a logger in a client project. When I made that change in the client's code base, I added the …
Continue reading "Saving 10 Minutes on Documentation Wasted Hours of My Client’s Time"
6 December 2021 by Phillip JohnstonDocumentation can help you slow down software aging. Although we note that it must be good documentation! Unfortunately, even when software is well-designed, it is poorly documented. You can reverse this course with retroactive documentation: investing in and upgrading the quality of the documentation post hoc. This will help you slow aging and possibly even rejuvenate the project. Correcting documentation is a major project, but it is worth the effort. Other benefits of upgrading documentation: Redoing the documentation often leads to improvements in the software. Errors are exposed, and then they can be fixed. Writing …
Continue reading “Good Documentation Can Slow Down Software Aging”
6 December 2021 by Phillip JohnstonBoth developers and researchers know that documentation is a real problem. Documentation is often considered a “dirty word” because it’s very often bad, and bad documentation gets ignored, leading to software aging. It’s reasonable to ask, “What makes bad documentation?” Documentation is bad if any of the following are true: Information is not available Information is incomplete Information is not correct Information is hard to find (poorly organized) Information is duplicated and possibly inconsistent Information is imprecise, easily misinterpreted The documentation is bulky Documents are not kept “alive” Documentation was written by people who do …
Continue reading “What Makes Bad Documentation”
6 December 2021 by Phillip JohnstonWe consider good documentation to exhibit the following qualities: It’s lean and concise, never bulky It’s well organized Information is not duplicated It’s up-to-date – changes were not allowed to get ahead of the documentation We can also tell that documentation is good, because it will be used in multiple contexts. For example, documentation that is started at the beginning of the project will be used at least six times: Used in discussions with users/customers and settle disputes if they do not like what they get Used in detailed and effective design reviews Used by …
Continue reading “What Makes Good Documentation”
30 October 2019 by Phillip Johnston • Last updated 9 October 2024Problem statement: code is not the only thing that matters. Why Documentation Matters Fundamentally, without documentation, nobody will know how to use your software. Even worse, in a couple of months you won’t know how to use your software either – especially if key members of the team depart. Documentation is valuable for many other reasons: Documentation is scalable, personal support is not. The efforts of an individual or group can be referenced by any number of individuals, reducing the support burden. Documentation can be used to aid training and …
Continue reading “Documentation”
