Robot software deployment and rollback checklist
What to record before a release goes out, so that reverting it at two in the morning is a procedure rather than a guess.
The short answer
A robot software release needs six things recorded as it happens: the exact configuration before and after, who approved it against what preconditions, what was validated at each stage and what was not, a rollback plan somebody has actually rehearsed, a briefing for the people who will see the new behaviour, and a watch period with a baseline to compare against.
The field everyone skips is whether the rollback has ever been performed. An untested rollback is a hope, and the moment you need it is the worst moment to find that out.
Download the release record (Markdown, 20 KB) · no email required, no account, nothing to accept.
Scope, and what this is not
This record is a proposal. No standards body publishes it, nobody has adopted it, and filling it in does not make a release safe.
It is not a safety assessment. Whether a change is safe to make at all is determined by a competent assessor for your application. Section 2 of the record asks you to check whether the change triggers re-assessment and to record the answer — it does not tell you what the answer is.
No automatic motion is prescribed anywhere. Nothing here instructs a robot to re-home, resume or recover on its own. Every step that produces motion is a step a person initiates, because an unattended recovery sequence is a design decision for your assessor, not a default.
The interaction between software rollback, firmware, calibration and the physical state of a machine is the part of this most in need of review by someone qualified, and nobody qualified has reviewed it. Those parts are written as questions for that reason.
Why a robot release is not a deploy
Shipping to a server has a property robotics does not get: the previous version is still sitting there, the state is in a database somebody else manages, and reverting is a command. None of that holds on a machine that moves.
Three differences do most of the work.
The thing you are changing is one layer of several, and you own the smallest one. Underneath the application sit middleware packages, a controller firmware the vendor flashed, a calibration somebody performed on a particular day, and a physical cell that has been adjusted since commissioning. Reverting your layer reverts your layer.
The system has physical state. A server mid-request can be killed. A robot mid-cycle is holding something, at a position, with a tool engaged. "Roll back" on a machine in that condition is a sequence, not a command, and the order of its steps is a decision somebody has to have made in advance.
A behaviour change is visible to people. If the capability now declines work it previously attempted, an operator who has not been told will report a broken robot. The next time it refuses for a real reason, nobody will look. That is why section 5 exists and why it is not optional.
1. Record the validated configuration
Two columns, now and after, across eleven rows: the capability version, the build artefact, the middleware distribution, the middleware packages that matter, controller firmware, every dependency that moved, sensor firmware and drivers, the operating system, the calibration set in force, the configuration files, and model weights if there are any. The diff between the columns is the release.
Two of those rows are a pair, and the pairing is the point. A package name is not a version. The same package carries a different version on every distribution — on 14 November 2026, the ROS 2 hardware_interface package's own index entry showed 2.54.4 under Humble, 4.50.0 under Jazzy and 5.20.0 under Kilted. Three major versions, one package name. Record the distribution and the package version together or neither tells you anything.
Then the field most teams fill in exactly once, at commissioning, and never revisit: when does your distribution's support window end? ROS 2 publishes a new distribution every twelve months, alternating long-term and short-term support, with an LTS supported for about five years and a non-LTS for roughly eighteen months. Those dates are published in advance, which means a robot commissioned onto a short-support distribution has a known expiry from day one — and it is usually nobody's job to notice it arriving.
Last, what the version number actually means. Semantic versioning says software using it must declare a public API, and that major version zero means anything may change at any time. On a robot the interface includes the operating envelope and the refusal behaviour, not just the message types — so a change that narrows what the robot will accept is a breaking change even though no code signature moved. If nobody wrote the envelope down, no version number can describe a change to it.
2. Define approvals and preconditions
Eight preconditions, each with evidence, a named confirmer and a date: the current configuration is recorded and recoverable, the change is tagged, whatever tests exist have been run with the result attached, the rollback plan is written and somebody has read it, affected operators have been told, a re-assessment trigger has been checked, a window is agreed, and the support owner knows it is happening.
The re-assessment check is a tick list of seven things a release might touch: the operating envelope, refusal behaviour, what happens on loss of a sensor or the network or power, stop behaviour and how the system resumes, anything a safety function depends on, anything that changes where people can be, and calibration or frames. Any tick is a question for whoever owns the risk assessment, asked before deployment.
The record does not tell you what re-assessment is required — it is in no position to. It tells you to ask, and it records the answer, so the next person can see the question was put and by whom. In the worked example that field is the one that produced the most useful sentence in the whole document, because the person who owns the assessment wanted her reasoning written down.
Approvals are names, not roles. A role cannot be telephoned at two in the morning.
3. Stage simulation and hardware checks
Three stages in order — simulation, bench or off-line hardware, then one robot out of production — and each one records what it did not cover alongside what it did. A simulation result without its limits is worth less than no result, because it invites the reader to assume coverage that is not there.
The bench stage carries one question that is easy to get wrong: is the bench hardware the same revision as the fleet? Often it is the newest unit, which makes it the least representative one.
The out-of-production stage asks for deliberate out-of-envelope trials: did it refuse cleanly? A release that handles the normal case and has never been pushed outside its stated limits has been half tested.
Then the section that earns the rest of its place: what was not tested at all. Shift patterns not covered, product variants not tried, failure modes not induced, robots at other revisions, the cold start on Monday. The honest answer is usually longer than the tested list, and the stage gate does not require it to be empty — only that a named person has accepted each gap.
4. Plan deployment and rollback
The plan covers order, spacing, who is physically present, whether the cell is clear of people, how the robot is brought to a known state first, and who initiates each step — a person, in every case.
Then the abort condition, written before you start, while nobody is invested in it succeeding. What we will see that means stop, who may call it, and how long we watch before accepting. A stop condition agreed in advance gets used; one invented during the incident gets argued about.
The rollback procedure is numbered steps somebody can follow cold — and then the field this page exists for:
Has this rollback been performed, not just written? On what, by whom, when, how long did it take, and what did it turn out not to restore. In the worked example the rehearsal is what revealed that step one needed to be "an operator takes the tote out of the gripper," which nobody had written down because on a bench there was never anything in the gripper.
5. Brief the operator and support owner
What changes that an operator will notice, what they should do differently, who they call and on what number, how a problem gets reported, and two questions that catch the usual gap: has the briefing happened, or only been written, and who briefed the shift that was not on duty?
One row matters more than the rest. What does a new behaviour look like, as distinguished from a fault? A capability that now refuses where it used to try has not broken, but it looks identical to broken from the outside. Tell people, or you will get a false alarm now and a missed real one later.
6. Monitor and close the change record
Six signals watched after deployment — completion, interventions, clean refusals, worst cycle time, unplanned stoppages, operator reports — each with a baseline from before the change. That column is why the record is filled in beforehand. Without it, "it seems fine" is the only verdict available.
Closing records the outcome, whether the rollback was used, what would be done differently, and two questions that reach outside this document: does the compatibility matrix need updating, and does the capability specification's status drop back to declared?
That last one has teeth. A specification claiming tested is making a claim about a configuration. Change the configuration without re-testing and the claim is false, so the status drops until somebody re-tests. A specification that stays at tested through a firmware upgrade nobody re-validated is actively misleading, and it is misleading in the direction that gets someone hurt rather than inconvenienced.
The states a release moves through
Seven states, and the useful property is where failure sends you.
The other property worth naming: nothing in that diagram advances on its own. There is no automation step, no promotion rule, no pipeline that moves a release forward because tests went green. Every arrow is a person deciding, and the record captures who. That is a deliberate constraint rather than an admission — on a machine that moves, an automatic promotion is a decision made by whoever wrote the pipeline, months ago, without seeing the robot.
What rollback actually restores
This is the table worth filling in honestly, because the gap between what people assume rollback does and what it does is where the bad hour comes from.
| Layer | Does reverting your package revert it? | What to check |
|---|---|---|
| Application code | Yes, if the artefact is still available. | Is the previous build still retrievable, or only its source? |
| Configuration and parameters | Only if they are versioned with the code. | Parameters edited live on the controller are not in your repository. |
| Model weights | Only if they are versioned and the old file is kept. | Weights are often large enough that old versions get pruned. |
| Middleware packages | Only with a pinned lockfile and an available mirror. | An unpinned dependency resolves to whatever is current at rollback time. |
| Controller firmware | Usually not. | On many controllers a firmware step is not reversible by the operator at all. |
| Calibration | No. | If a calibration was redone during the release, reverting software leaves the new one in place. |
| Physical state | No. | A robot holding a load is still holding it. Who removes it, and at which step? |
| Time | No. | Rollback takes the time it takes. On a machine that holds a load or maintains balance, the sequence matters more than the speed. |
The record asks you to tick only the rows that are true for your machine, and then to write the unticked ones out in plain words. If the answer to a row is “we do not know,” that is the answer — and it is a finding worth more than a confident guess.
The release record
References
Three primary documents, with the version read and what was checked in each:
- REP 2000 — ROS 2 releases and target platforms
Checked 14 November 2026. States that new ROS 2 releases are published on a time-based schedule every twelve months, alternating LTS and non-LTS; that an LTS aims to match the five-year standard support of the corresponding Ubuntu LTS; and that non-LTS releases are supported for 1.5 years. Section 1.12 of the record asks you to read the current window from this document rather than from here, because those dates move. - Semantic Versioning 2.0.0
Checked 14 November 2026. MAJOR for incompatible API changes, MINOR for backward-compatible functionality, PATCH for backward-compatible bug fixes; major version zero is for initial development and anything may change at any time; and software using it must declare a public API. That last requirement is the basis for section 1.13 — without a declared interface, a version number is decoration. - hardware_interface — ROS Index package summary
Checked 14 November 2026. Showed version 2.54.4 under Humble, 4.50.0 under Jazzy and 5.20.0 under Kilted. Cited only as evidence that one package name spans several major versions depending on distribution, which is why section 1 asks for both together. - CC BY 4.0
The licence this record is published under.