Maintenance and Efficiency

Release Management: Versions, Acceptance, Handover and Support

How to treat a release as a deliberate decision about what is ready for whom, separate from versions, artefacts and deployments, and how to accept,…

Chapter 68Maintenance and Efficiency

Picture the team behind an editorial platform shipping a new way to manage the publishing schedule. The code has passed its checks, the package has been built and the production service has been updated. Does that mean editors can now reschedule planned stories? Do they know which publications the new action applies to? Who will check the first rescheduling, answer questions and decide what to do if the confirmation email never arrives?

A release is an agreed decision about which changes are ready for a defined audience, how they will be announced and who accepts the result once the technical deployment is done. The idea covers code, data, configuration, documentation, expectations, support and accountability. The technical steps of deploying and verifying a system are covered in Continuous Delivery and Deployment; this unit focuses on the product and client side of the same process.

Learning outcome. After this unit you can tell a version apart from a release, an artefact, a tag in the code history, a deployment and the switching-on of a feature; define what a release contains and where its limits are; check readiness and acceptance criteria; write clear messages for different audiences; and hand over support with clear lines of responsibility.

Name exactly what is being released

In conversation, "version", "release" and "deployment" are often used as synonyms. They are related, but they mean different things.

  • Version — a label for a state of the product or of a contract, such as "2.4.1". What the number means depends on the policy of that particular product.
  • Tag — a marker in the version-control history that points to a specific revision. A tag lets you find the code, but on its own it does not show that the code has been checked, built or made available to users.
  • Artefact — a concrete built package, image or other output that can be passed on. For reproducibility, record the exact revision, the artefact's identifier or digest (its cryptographic fingerprint) and the build parameters that matter.
  • Deployment — installing an artefact, together with its configuration, in a particular environment. The same version can be deployed several times, or first only for an internal audience.
  • Feature enablement — changing whether a specific capability is available, for example through a feature flag or separate access permissions. The code can be in production while the feature stays switched off for most users.
  • Release — a managed set of changes and decisions for a defined audience: what is ready, how and when it becomes available, what people need to know, which limitations apply and who supports the result.

So one version can be rolled out in stages, and one release can span several components and several messages. A message to a client should state not only the version number but also availability and the conditions of use. The team's own record should tie the decision to a verified artefact and revision. This stops anyone from treating a successful deployment as proof that users are already getting value.

When semantic versioning fits

Semantic Versioning (SemVer) sets rules for a declared public application programming interface (API): the major number marks an incompatible change to the contract, the minor number marks compatible new functionality, and the patch number marks a compatible fix. The scheme only makes sense once the team has defined which public contract it supports and what compatibility means for it.

Not every website, report, internal tool or business process has such a contract. For those, a team may choose calendar-based labels, a project number or some other policy that suits how it works. For a data format, the compatibility rule can be separate from the version of the web application. Do not bump the number "to a major" just because the changes feel big, and do not keep it low if consumers have to rework their integration.

Once a team has published a version under SemVer, its contents must not change. A corrected package gets a new version label and a traceable link to the previous one. For other products the same audit principle is useful: users should be able to tell exactly which set of changes they received.

Define the boundaries of the release

Before preparing a release, state its outcome for a specific audience. A list of commits is not an adequate description: it answers "what did the developers change", not "what can the user now do".

A short statement of the release scope should cover:

  1. Who the changes are for and what problem they are meant to solve.
  2. Which features, fixes or changes in behaviour are included.
  3. What has been deliberately postponed or is available only to a particular audience.
  4. Which dependencies, preparatory steps or data changes are required.
  5. Which known limitations remain and what the user should do about them.
  6. Which observation will confirm that the expected outcome has been achieved.

In Shape Up, Ryan Singer describes fixed time limits and deliberate scope cutting: when the work does not fit, the team protects a finished core of the outcome by dropping secondary parts. This is useful for releases: it is better to ship a complete scenario with its limitations named than to hide an unfinished part behind a general "done". But deliberate scope cutting does not excuse skipped acceptance criteria, a hidden defect or a missing migration that safe use depends on.

Mark a postponed feature plainly. Do not describe it as available, do not put it in screenshots or a demo without explanation, and do not leave a non-obvious toggle the client could switch on. When a dependency is not ready, record how that affects availability and support.

Check readiness for the release decision

Readiness does not mean that every item on a universal checklist is mandatory for every change. It means the team has considered the risks that apply and has evidence for its decision. A small text-only release may not need sign-off from several teams; a change to data, permissions or an external contract will need more attention.

Before deciding to release, ask:

  • Are the audience, the boundaries, the postponed items and the acceptance criteria defined?
  • Are the exact revision and the artefact to be passed on known?
  • Have the specific checks that the notes refer to actually been run, and can their results be shown?
  • Are there changes to data, configuration, access or external dependencies? Is it known how they affect compatibility?
  • Are the documentation, the short user message and the instructions for support ready?
  • Is it settled who decides on availability and who is on call for the result?
  • Is it clear which signals to check after the release and under what conditions further rollout stops?
  • Are handovers, the required permissions and the contact for problems agreed?

The technical side of deployment, gradual rollout and recovery is covered in Continuous Delivery and Deployment and Deployment Strategies. At the level of release management, what matters is linking the technical plan to the decision: which revision goes ahead, who judges the signal and whom to tell about a problem. A plan for going back does not always mean simple undo: after an irreversible data change, a fix forward may be needed. Do not promise a rollback until the team has checked that it is possible for this particular artefact and this state of the data.

Record each item's status as "verified", "not applicable, because…" or "unknown / blocks the decision". Do not replace "unknown" with an assumption. If an unknown does not block the release, name the owner of the risk and the condition under which it will be reviewed.

Separate technical records from messages for people

A single release has several audiences, so it helps to have at least three short records:

  • A changelog for the product's history: a structured list of changes, fixes and incompatibilities.
  • Internal release notes for the team: revision, artefact, checks, dependencies, decisions, limitations and the people responsible.
  • A message to the user or client: the change in plain terms, its benefit, availability, any action required and the limitations.

Not every internal technical record needs to be published. But do not hide from a client a limitation that changes their decisions or the way they work. Explain it in accessible language and say what to do.

A useful message answers these questions: what changed; who has access to it; what needs to be done; whether the familiar workflow changes; where to go with questions. It does not promise a date for a future release or round-the-clock support unless that has been agreed. If the team has not yet confirmed that an action has happened, the text must not give the impression that it has.

Account for migrations, compatibility and deprecation

A change to a format, a field, permissions or an integration may require the client to act. Describe the transition together with its sequence: what can be prepared in advance, which new behaviour is compatible with the old, how to check success, what to do if something fails and who has access to the system involved.

For data structures it is often safer to go through several compatible stages: first add the new shape, then move or synchronise the existing data, check it, and remove the old shape only once nothing needs it any more. This order is an example for a particular context, not a universal requirement. The details of technical migration and recovery belong to Continuous Delivery and Deployment and Deployment Strategies; release management requires that the consequences are spelled out for the user and for the operational owner.

Retiring an old interface or workflow should be announced in advance, in line with the product's actual policy. If the deadline is unknown or not agreed, do not make one up. Say exactly what is being retired, which transition options are confirmed and who can answer questions. A feature flag also needs an owner and a plan for removing it: hiding something temporarily does not remove the old code path, the outstanding actions or the support it requires.

Accepting professional work and handing it over

In client work, "the code is ready" and "the result has been accepted" are different statements. David Maister connects professional services to the quality of the relationship, to adapting to the client's needs and to agreeing what work the professional actually does. That gives a practical rule: before work starts and again at handover, re-check the expected outcome, the boundaries of the service and who owns the next step.

Acceptance criteria should describe an observable result agreed with the product owner or the client. "The integration is done" is too thin if it is unclear which systems and cases it covers. The criteria can name the supported scenarios, the access required, what data is transferred, known exceptions and how the result will be confirmed. Do not substitute a deployment notice for agreement on the result.

A handover to the operational owner should include:

  • what has been handed over, who it works for and where the supported scenario ends;
  • the documentation and links to the relevant records;
  • the system owner, the contact and the procedure for reporting an incident;
  • known risks, limitations, dependencies and what to watch after the release;
  • which access rights are needed and who grants them — with no passwords, keys or tokens in the note;
  • what the development team will support and what will need separate agreement.

A description like this keeps a limited engagement from turning into an implicit promise to support any integration with no time limits or boundaries. It is not a legal template: specific obligations, prices and timelines are agreed by the responsible people according to the organisation's rules. A technical author can spot an ambiguity and propose clear wording, but does not set commercial terms on their own.

After the handover, plan a short feedback conversation: was the expected outcome achieved, what turned out to be unexpected, did the instructions work, is a separate follow-on piece of work needed. Maister stresses the importance of collecting client feedback and using it to improve the service. Such feedback does not mean that every requested change is automatically part of the scope already agreed.

Small releases should serve value and reliability

Research on software delivery performance by DevOps Research and Assessment (DORA), and the book Accelerate, link the ability to deliver changes frequently with working in small batches, short feedback loops and a reliable process. That does not mean every team should chase release frequency. DORA describes deployment frequency as one of its metrics and explicitly warns against turning it into a goal in itself. Changes should reach users regularly and with a level of risk that is acceptable for the specific product.

Small batches make it possible to notice a problem closer to its cause, get feedback sooner and change the plan. If a client needs an agreed window or advance preparation, the team may choose a less frequent but predictable release. What matters is keeping repeatable readiness criteria, a clear owner of the decision and a way to find out what happened after the release.

Metrics do not replace an assessment of the user outcome. A team can count the time from change to use, the number of releases or incidents, but it should also check whether users completed the task they needed, whether support requests went up and whether new manual work appeared. Choose metrics that help the team learn, not ones that hide problems or punish people for circumstances outside their control.

Where an agent's actions stop

An agent can gather changes from the history, match them to requirements, find missing evidence, check links, draft internal notes or a client message, and list what is unknown. It must clearly separate verified facts from assumptions. If a check was not run, it must not write that the check passed.

Publishing a message to a client, switching a feature on for an audience or deploying are actions with external effects. An agent performs them only with the appropriate permission inside the existing process — not because it can propose the command or can see the button. If its authority is ambiguous, it prepares the materials and names the specific decision that a responsible person has to make.

Fully worked examples

Example 1: An editorial calendar release with a migration and a postponed notification

The editorial platform team is adding the ability to reschedule a publication that is already planned. The new action must keep a change history, check that the editor is allowed to manage the story, and never create two active publishing jobs for the same article. The team had also planned push notifications, but the provider has not yet approved the template.

Release boundary. An editor can reschedule a story that was scheduled in the new system after an agreed date; users with management rights can see the change history. After rescheduling, the author receives an email. Push notifications are postponed, so the release announcement names this limitation directly and the interface does not promise the feature. Older stories can be viewed, but for now an operator has to change their schedule. The product owner checks these criteria.

Version and artefact. The platform's clients use a defined API. A new optional field with the rescheduled time is added to the response; the team checks against the supported consumers that they ignore unknown fields. Under this API's policy such a field is compatible, so the version gets a minor bump. For other APIs that conclusion has to be drawn from their own contract. If the compatibility check fails, the team needs a different contract version and a plan for moving consumers over before the feature is opened. In the internal record, the team captures the tag of the source revision, the artefact identifier, the environment configuration and the results of the checks.

Schema change. The history of reschedulings is stored in an additional table; older stories are not rewritten. Before the migration, the team defines the expected number of records and a stop condition; afterwards it reconciles the count and state of the stories against the result of a dry run. Before editors get access, it checks that history is created, that story permissions hold and that there are no conflicting active publishing jobs. If the migration goes wrong, the team halts the rollout and uses its verified data recovery plan. It does not promise a return to the previous schema, because that could erase the new history.

Message to users. "Editors can now move a new publication to another free date in the 'Editorial calendar' section. After the change we will send a confirmation by email. For now, older stories can be rescheduled by an operator. Push notifications are not part of this release. If the new date does not appear, contact support and include the title of the story."

Operational checklist before the decision.

  1. Reconcile the revision, artefact, environment configuration and check results for this candidate — so the team and support are checking the same release.
  2. After the migration, reconcile the number and state of stories and confirm the history table exists — so that loss or duplication is caught before access is opened.
  3. Check editor permissions and the absence of duplicate active publishing jobs — to confirm that the right person moves the story and that it will not be published twice.
  4. Make sure the instructions for older stories and the support contact are available to the person on call — so the first support request does not depend on the author of the change.
  5. Define the signals to watch after enablement — successful reschedulings, and errors or duplicates in the queue — and the owner who watches them.
  6. Name the condition for halting the rollout and rely only on the verified recovery plan — so the team knows when to stop widening the audience and how to handle the data.
  7. Get the product owner's confirmation against the acceptance criteria for the defined audience — the button being available does not, on its own, mean the result has been accepted.

After the decision, the product team reviews support requests on the next working day. The release counts as accepted for this audience when the criteria are met and the owner has confirmed the expected scenario.

Example 2: A client expects unlimited support for an integration

A client ordered an export of aggregated platform usage data into their own reporting warehouse. After the demo they say: "Great — so now you'll make sure this export keeps working with any future version of our system, right?" The agreed outcome described one export schema and a check against the client's test environment, not open-ended maintenance of their third-party system.

The author does not start by arguing about intentions; first they restate the agreed outcome: "We delivered the usage data in format X and checked the export against the test version of system Y. We have not yet agreed on ongoing monitoring or adapting to future versions." That way the team names the boundary without blaming the client.

Next, the team hands over what is needed to actually use the export: a sample file without personal data, a description of the fields, the time the export is generated, instructions for re-running it, error notifications, and the contact responsible for access to the client's environment. Secrets are passed through an approved access mechanism, not as an email attachment. The record states who handles reports of a product defect and where questions about configuring the third-party system should go.

For future maintenance, the team proposes defining the required level separately: for example, support for a specific version, how often it is checked, the owner of the contact and how changes are agreed. It does not promise timelines or a price without a decision from an authorised person. The client and the service owner agree whether this follow-on work is needed; the current acceptance closes against the criteria agreed earlier. Framing it this way preserves the working relationship and avoids creating an unnoticed obligation for the future.

Example 3: Turning change titles into meaningful notes

An online shop's technical log contains three titles: "Add index to order_status", "Fix time zone in return form" and "Remove legacy catalogue import toggle". Copied into a client email, they would tell the client about internal decisions but not about the benefit, availability or consequences.

The author checks the changes and confirms these facts: the order list opens faster in shops with large amounts of data; the return form now shows the time in the shop's time zone for Oslo and London; the old catalogue import is switched off only after a shop has moved to the new format. Nothing in the change records confirms that all shops have already moved, so the notes do not claim it.

The rewritten text for users: "The order list opens faster in shops with large amounts of data. In the return form, times are shown in the shop's time zone for Oslo and London. The old catalogue import is switched off only for shops that have already moved to the new format. If you still use the old one, contact support before access is switched off."

The internal notes keep the change titles, the exact revision and the evidence; the changelog classifies the retirement of the old import as an incompatible change. A responsible person has to confirm the list of shops still using the old format and the team's right to notify them. Without that evidence, the text about switching it off is not published until the owner clarifies the audience and the required action.

Example 4: The Grafana Tempo 3.0 release as a source of concrete actions

The public release of Grafana Tempo 3.0.0 on 28 May 2026 shows why a general note saying "version 3.0 is available" is not enough for operators. The release description links to the notes and to separate migration instructions. For a microservices deployment, the documentation describes preparatory checks, running Tempo 2.x and 3.0 in parallel, verifying the components and access to historical queries, and then gradually switching traffic over. Running in parallel increases infrastructure costs. Once the old environment has been removed, simply routing traffic back is no longer enough — recovering would mean deploying Tempo 2.x again. For monolithic mode the migration path is simpler.

A team writing its own announcement about a change like this should not copy every technical step into short user notes. It should identify who the operator is, give that person instructions for their type of environment, flag the temporary costs and the limits of going back, and explain to users only what affects them. A link to the release does not prove that a particular environment migrated successfully; acceptance needs its own check of that environment. The main lesson of the example is to combine the real artefact, instructions for the right owner and a separate confirmation of the result.

Sources and further reading