Chapter 5 · Quality, Release and the Future
Releasing and Maintaining Software
- Page 16 of 18
- 19 min read
The tests pass and Nadia has accepted ClinicQueue. Now it has to reach real patients, and that is a moment where careful teams slow down. A release is a promise that this exact version works, and a plan for what to do if it does not. After the release, the software enters its longest phase: years of fixes, adjustments and improvements, done by people who may not remember why the code looks the way it does.
On the previous page, Software Quality, Testing and QA, you saw how the team knows a build is good. This page follows that build out of the door: how to number versions with Semantic Versioning (with a small Python function), what goes into release notes and a rollback plan, why software passes through several environments, the four kinds of maintenance, technical debt, and the documents that make maintenance possible. ClinicQueue's versions, dates and problems are invented.
What you will learn
- How Semantic Versioning (SemVer 2.0.0) numbers releases, and how to compute the next version with a few lines of Python.
- What good release notes and a rollback plan contain.
- Why teams use separate development, testing (staging) and production environments.
- The four types of maintenance (corrective, adaptive, perfective, preventive) with ClinicQueue examples.
- What technical debt is, how it builds up and how teams pay it down, and which documents (README, change log) help the next maintainer.
Releasing a version
A release is a specific, identified version of the software made available to its users. "Identified" is the important word: when Rina reports a problem, the team must know exactly which code she is running. So every release gets a version number, and the commit it was built from is marked in version control (Git tags are the usual way; Git itself is covered in Git, APIs and Backend for AI: Beginner).
Semantic Versioning
Many projects follow Semantic Versioning 2.0.0 (semver.org), a published convention for version numbers of the form MAJOR.MINOR.PATCH. It is a specification that projects choose to follow, not a law or an ISO standard. Its three rules, in its own words, say to increment the:
- "MAJOR version when you make incompatible API changes",
- "MINOR version when you add functionality in a backward compatible manner",
- "PATCH version when you make backward compatible bug fixes".
The lower numbers reset when a higher one goes up: "Patch version MUST be reset to 0 when minor version is incremented", and "Patch and minor versions MUST be reset to 0 when major version is incremented". So after 1.4.7 comes 1.4.8 (a fix), 1.5.0 (a feature) or 2.0.0 (a breaking change), never 1.5.7 or 2.4.7.
Three more rules matter early. "Major version zero (0.y.z) is for initial development. Anything MAY change at any time." "Version 1.0.0 defines the public API", meaning from then on the numbers make promises. And extra labels are allowed: a pre-release adds a hyphen and dot-separated identifiers (1.0.0-alpha.1), and build metadata adds a plus sign (1.0.0+20130313144700).
What is ClinicQueue's "public API"? SemVer is written for software that other programs depend on. For ClinicQueue, that is the booking API that the clinic's website widget calls. If a change forces the widget to change too, it is incompatible, and the major number goes up. A change that patients only see on screen is usually a minor or patch release.
A version bump in Python
The rules are mechanical, so a short function can apply them. Lena keeps a list of the kind of each release since the test build 0.9.3:
def bump(version, part):
"""Next Semantic Versioning 2.0.0 version for a 'major', 'minor' or 'patch' change."""
pieces = version.split(".")
if len(pieces) != 3 or not all(p.isdigit() for p in pieces):
raise ValueError(f"not a plain MAJOR.MINOR.PATCH version: {version}")
major, minor, patch = (int(p) for p in pieces)
if part == "major":
return f"{major + 1}.0.0" # minor and patch reset to 0
if part == "minor":
return f"{major}.{minor + 1}.0" # patch resets to 0
if part == "patch":
return f"{major}.{minor}.{patch + 1}"
raise ValueError(f"unknown part: {part}")
# ClinicQueue releases after the test phase (invented)
releases = [
("major", "first stable release for real patients; booking API frozen"),
("patch", "fix: holiday dates were shown as open slots"),
("minor", "add: reminders in Bangla"),
("patch", "fix: some patients got the SMS twice"),
("minor", "add: AI-drafted reminder text, off by default"),
("major", "change: every booking API call now needs a clinic id"),
]
version = "0.9.3"
for part, note in releases:
new = bump(version, part)
print(f"{version:>6} -> {new:<6} {part:<6} {note}")
version = new 0.9.3 -> 1.0.0 major first stable release for real patients; booking API frozen
1.0.0 -> 1.0.1 patch fix: holiday dates were shown as open slots
1.0.1 -> 1.1.0 minor add: reminders in Bangla
1.1.0 -> 1.1.1 patch fix: some patients got the SMS twice
1.1.1 -> 1.2.0 minor add: AI-drafted reminder text, off by default
1.2.0 -> 2.0.0 major change: every booking API call now needs a clinic idThe jump from 0.9.3 to 1.0.0 is the moment the booking API became a promise. The Bangla reminders and AI drafts add features without breaking anything, so they are minor releases. The last change breaks every caller that does not send a clinic id, so it must be 2.0.0, even though the code change itself was small. The version number describes the effect on users of the API, not the size of the work.
The function only accepts plain MAJOR.MINOR.PATCH versions and refuses anything else instead of guessing. Pre-release labels and a "v" prefix (common in Git tag names) are left out to keep it tiny:
for text in ["1.2", "1.0.0-alpha.1", "v1.2.3"]:
try:
bump(text, "patch")
except ValueError as error:
print("refused:", error)refused: not a plain MAJOR.MINOR.PATCH version: 1.2
refused: not a plain MAJOR.MINOR.PATCH version: 1.0.0-alpha.1
refused: not a plain MAJOR.MINOR.PATCH version: v1.2.3Letting commit messages choose the bump
One popular convention, Conventional Commits 1.0.0, links commit messages to SemVer. A message starts with a type, an optional scope and a colon: fix(sms): retry once. A fix maps to PATCH and a feat to MINOR; a ! before the colon or a BREAKING CHANGE: footer marks a breaking change and maps to MAJOR. Other types such as docs, test and refactor are allowed. It is a convention some teams choose, not a requirement. Imagine the team is still on 1.2.0:
def next_version(version, commits):
"""Choose the bump from Conventional Commits messages: breaking > feat > fix."""
headers = [message.split(":")[0] for message in commits]
if any(h.endswith("!") for h in headers) or any("BREAKING CHANGE:" in m for m in commits):
return bump(version, "major")
if any(h.split("(")[0] == "feat" for h in headers):
return bump(version, "minor")
if any(h.split("(")[0] == "fix" for h in headers):
return bump(version, "patch")
return version # only docs, tests, refactoring: no new release number
print(next_version("1.2.0", ["fix(sms): retry once when the provider times out",
"docs: explain the reminder settings"]))
print(next_version("1.2.0", ["feat(queue): show an 'arrived' mark", "fix: typo on the queue screen"]))
print(next_version("1.2.0", ["feat(api)!: require a clinic id in every booking call"]))
print(next_version("1.2.0", ["test: add boundary tests for can_book"]))1.2.1
1.3.0
2.0.0
1.2.0The highest-impact commit wins: a feature plus a fix is a minor release. Commits that only touch documentation or tests do not need a new version at all.
Release notes
Release notes tell users and support staff what changed in a release, in their language, not the developers'. Rina does not need "refactored slot service"; she needs "holiday dates are no longer shown as open slots".
Template:
ClinicQueue 1.1.0 - released 2026-11-30
New
- Reminders can be sent in Bangla. Choose the language in Settings > Reminders.
Fixed
- The queue screen now shows bookings made after 17:00 for the next day.
Known issues
- The queue screen does not yet show the "arrived" mark. Planned for a later release.
Action needed
- None for patients. Front desk: check the reminder language for each doctor once.
Questions: Lena (project lead)A rollback plan
A rollback returns production to the previous working version when a release goes wrong. Plan it before the release, when everyone is calm, not at 09:05 on launch day with patients waiting. The hard part is usually data: if the new version changed the database, the old version may not understand it any more.
Template:
Release: ClinicQueue 2.0.0 (booking API needs a clinic id)
Previous version: 1.2.0, build kept ready to redeploy
Go/no-go: Nadia and Lena, 2026-12-20 18:00, after the staging check
Roll back if: bookings fail for more than 5 minutes, or reminders stop being sent
How: redeploy 1.2.0 (about 10 minutes, Farhan); website widget keeps its old version
Data: database change only ADDS a column, so 1.2.0 still works with it
Who decides: Lena, on call 18:00-22:00; Farhan and Kwame on call with her
Tell users: front desk by phone; a notice on the booking page if it takes longer than 30 minNotice the data line. Designing changes so the old version still works with the new data (adding a column instead of renaming one) is what makes a rollback possible at all. Some teams also hide a risky feature behind a setting, as ClinicQueue did with the AI drafts ("off by default"), so they can switch it off without a redeploy.
Environments: development, staging, production
An environment is a complete place where the software runs: the servers, database, configuration and connected services. Teams keep several, so that experiments and tests never touch real patients.
| Environment | Purpose | Data | ClinicQueue example |
|---|---|---|---|
| Development | Where developers write and try code | Small invented data | Farhan's laptop; SMS goes to a fake sender that only prints |
| Testing / staging | A copy of production for system and acceptance tests | Realistic but invented, or properly anonymised | The test server where Kwame and Nadia test; SMS only to the team's own phones |
| Production | The real system used by real users | Real patient data | The clinic's live booking site |
Example:
developer laptop test / staging server production
+----------------+ +----------------------+ +--------------------+
| write + unit | ---> | same build 2.0.0 | ---> | same build 2.0.0 |
| tests | push | system + acceptance | go | real patients |
| fake SMS | | team phones only | | real SMS provider |
+----------------+ +----------------------+ +--------------------+
only the configuration differs (addresses, keys, SMS sender), never the codeTwo habits make environments useful. First, promote the same build from staging to production; rebuilding "the same code" for production can quietly include something different. Second, keep the configuration (passwords, SMS keys, database addresses) outside the code, different per environment. And keep real patient data out of development and testing: it protects patients, and in many countries data-protection laws limit how real personal data may be used, so check the rules that apply to your project.
Maintenance: the longest phase
Maintenance is everything done to the software after delivery. The international standard for it is ISO/IEC/IEEE 14764 (current edition 2022, which replaced the 2006 edition), and it establishes definitions for the types of maintenance. The Software Engineering Body of Knowledge (SWEBOK), citing the 2006 edition, describes four types:
| Type | Meaning | ClinicQueue example |
|---|---|---|
| Corrective | "Reactive modification … after delivery to correct discovered problems" | Fix the double SMS that patients reported (1.1.1) |
| Adaptive | Keep the software usable "in a changed or changing environment" | The SMS provider retires its old interface, so the reminder module moves to the new one |
| Perfective | "Provide enhancements for users … improve software performance, maintainability, or other software attributes" | Add the "arrived" mark Rina asked for; make the queue screen load faster |
| Preventive | "Detect and correct latent faults … before they become operational faults" | Kwame notices that dates are stored without a time zone; it has not failed yet, but it will if the clinic opens a branch in another time zone, so the team fixes it now |
SWEBOK groups corrective and preventive maintenance as corrections, and adaptive and perfective as enhancements. The categories help planning: if most of the team's time goes to corrective work, quality earlier in the process needs attention; if adaptive work keeps surprising the team, someone should watch the services ClinicQueue depends on.
In practice the borders blur. Upgrading to a newer version of a library can be adaptive (the old one is no longer supported) and preventive (it closes a known security hole) at the same time. Pick the main reason; the category is a planning tool, not a legal label.
Technical debt
Ward Cunningham coined the debt metaphor in a 1992 experience report (OOPSLA '92) about the WyCash portfolio management system: "Shipping first time code is like going into debt." As Martin Fowler explains the metaphor, the extra effort that every later change in a messy area costs is the interest. A shortcut is like borrowing: you gain time now and pay interest until you clean the area up, which is like paying back the loan itself (the principal). Debt is not always a mistake; borrowing to meet an important date can be a sound choice, if you know you did it and plan to repay.
How it builds up
- Deliberate shortcuts: to launch on time, Farhan hard-coded the clinic's opening hours instead of making them a setting.
- Learning later: the team now understands the queue better than when they designed it, and the old design fits badly.
- Missing tests and documents: nobody dares to change the reminder scheduler because nothing would catch a mistake.
- Ageing dependencies: libraries fall behind and each upgrade becomes harder.
- Copy and paste: the same date check exists in three places, and a fix in one is forgotten in the others.
Paying it down
The first step is to make debt visible. ClinicQueue keeps debt items in the same backlog as features, with the interest written down so the product owner can weigh them:
Example:
ID Debt Interest (what it costs us) Size
TD-03 Opening hours hard-coded every new clinic needs a code change + release S
TD-05 No tests for the reminder scheduler each change takes a day of manual checking M
TD-08 Date check copied in three places bug CQ-212 had to be fixed three times SThen teams choose how to repay. Practitioners disagree about the best way:
| Approach | For | Against |
|---|---|---|
| Clean as you go: improve the code you are already changing | Steady, cheap, pays first where interest is highest | Areas nobody touches never improve |
| Reserve part of every sprint for debt items | Predictable; the product owner sees the trade-off | Easy to cancel under deadline pressure |
| A dedicated clean-up period | Good for big items, like a library upgrade | No new features for a while; debt grows again afterwards |
| Rewrite from scratch | Sometimes the only option for a tiny, badly broken part | For a whole system it is slow and risky, and the old system's hidden knowledge is lost |
For a small team like ClinicQueue's, the first two together usually work best: refactor as you go (the refactoring steps from Writing Maintainable Code), and give the most expensive debt items a place in each sprint.
Documentation that helps maintenance
The person who fixes ClinicQueue in two years may be a new developer, or Farhan, who will have forgotten the details. Two short documents in the repository do most of the work.
README
The README is the front door of the code: what this is and how to get it running. Keep it short and correct; a wrong README is worse than a short one.
Template:
ClinicQueue
Online booking, SMS reminders and a front-desk queue for a small clinic.
Run it locally: steps to install, configure (copy the example settings file) and start
Run the tests: the one command that runs all unit and integration tests
Configuration: which settings exist, which are secret, where each environment keeps them
Release: how a version is built, tagged, deployed and rolled back (link to the checklist)
Architecture: one paragraph and the component diagram from Software Design Basics (p11)
Contacts: who owns the code, who to ask about the clinic's rulesChange log
A change log is a file that lists the notable changes of every version, newest first. Release notes speak to users about one release; the change log is the full history for developers and maintainers. Both come from the same facts, and it is easiest to update the change log in the same pull request as the change.
Example:
2.0.0 - 2026-12-20
Changed (breaking): every booking API call needs a clinic id. Widget 3.x sends it.
1.2.0 - 2026-12-10
Added: AI-drafted reminder text, off by default (setting: reminders.ai_draft).
1.1.1 - 2026-12-02
Fixed: some patients received the SMS reminder twice (CQ-230).
1.1.0 - 2026-11-30
Added: reminders in Bangla. Fixed: queue screen missed bookings made after 17:00.Useful extras, when the project grows: a short record of important design decisions and why they were made, and comments that explain why where the code alone cannot.
Where this shows up at work
- Libraries and APIs you install announce SemVer numbers; a new major version is your signal to read the change log before upgrading.
- Teams hold a short go/no-go check before a release and keep a rollback plan in the release ticket.
- Joining a team usually means working on existing code, not starting a new system; adaptive work such as library and platform upgrades never stops.
- Freelancers often sell maintenance after delivery as a separate agreement, which is easier to price when the four types are named.
Common mistakes
- Choosing the version number by feeling. A "small" change that breaks callers released as a patch breaks other people's systems. Fix: judge the effect on the API, not the size of the change, and apply the SemVer rules.
- Releasing without a rollback plan. Under pressure, people improvise and make it worse. Fix: write the plan, including the data question, before the go/no-go meeting.
- Testing in one environment and deploying a different build. Fix: promote the exact build that passed staging, and keep only configuration different.
- Treating technical debt as invisible. It still charges interest. Fix: record debt items with their cost and give them backlog space.
- Letting the README and change log go stale. Fix: update them in the same pull request as the change, and check it in code review.
Try it yourself
- Easy: ClinicQueue's booking API is at 1.4.2. What is the next version after each change, applied one after another? (a) fix the wrong time shown for evening slots; (b) add an optional "reason for visit" field; (c) remove the old endpoint that returned slots as plain text, which some partners still use. Check your answer with
bump. - Medium: Name the maintenance type of each task: (a) the phone operating system changes how notifications work, so the reminder link must change; (b) patients report that cancelling shows an error; (c) Nadia asks for a weekly no-show report; (d) Farhan finds that slot numbers will overflow a small database column after a few thousand bookings, long before it happens.
- Hard: The AI-drafted reminder text (added in 1.2.0, off by default) will now be switched on for all patients; the current version is 2.0.0. Write a short release plan: the version (and why), three lines of release notes for the front desk, the rollback trigger and how to roll back, and one technical-debt item the team should record.
Answers
- (a) a backward compatible bug fix: 1.4.3. (b) a new optional field is new functionality that does not break existing callers: 1.5.0 (the patch resets to 0). (c) removing something callers use is an incompatible API change: 2.0.0 (minor and patch reset). Running
bump("1.4.2", "patch"), thenbump("1.4.3", "minor"), thenbump("1.5.0", "major")gives 1.4.3, 1.5.0, 2.0.0. - (a) adaptive: the environment changed. (b) corrective: a discovered problem after delivery. (c) perfective: an enhancement for users. (d) preventive: a latent fault fixed before it becomes an operational fault.
- Model answer: "Version 2.1.0 is a reasonable choice: turning the feature on for everyone is a visible new behaviour, but existing API callers keep working, so it is a minor change, not a major one; if it is only a setting change with no new code, the team may decide no new version is needed and record the change in the change log. Release notes: 'Reminder texts are now written for each booking by an AI tool and checked by rules and approved by the front desk before sending. If a text fails the checks, the old standard text is sent. Tell Lena if a patient reports a strange reminder.' Rollback: if the rule checks fail for many drafts in a day, or any reminder contains medical details or the wrong patient's data, Lena switches the setting off (no redeploy, under a minute); the standard text is used again. Debt item: 'The banned-words list lives in the code; moving it to a setting would let Kwame update it without a release.'" A good answer gives a version with a reason tied to the API rule, writes notes in the front desk's language, has a concrete and measurable rollback trigger, uses the "off by default" switch as the rollback method, and records a debt item with its interest.
Summary
- SemVer 2.0.0: MAJOR for incompatible API changes, MINOR for backward compatible features, PATCH for backward compatible fixes; lower numbers reset to 0; 0.y.z is initial development and 1.0.0 defines the public API.
- Every release needs release notes in the users' language and a rollback plan written in advance, including what happens to the data.
- Development, staging and production environments keep experiments away from real users; promote the same build and vary only the configuration.
- Maintenance is corrective, adaptive, perfective or preventive (ISO/IEC/IEEE 14764; current edition 2022).
- Technical debt (Ward Cunningham, 1992) charges interest on every change; make it visible and repay it steadily. A short README and an up-to-date change log help the next maintainer most.
Next: Software Engineering with AI Coding Assistants: how to use AI coding tools across the life cycle without giving up ownership of your code.

