Release Notes for Embedded Products: Turn Each Behavior Change into a Customer Action

For each release change, tell the affected reader whether they must act, what prerequisite applies, which approved procedure to use and how to recognize the expected result. A list of commits rarely answers those questions. Useful embedded release notes connect changed behavior to an operator, integrator or maintainer decision.

This article supplies a drafting and review method, not a release announcement for a real product. No installation was performed and no customer commitment is made. Actual update procedures, service terms and supported configurations must come from the authorized project records.

1. Start from observable differences

Review changes against the preceding supported release: commands, data fields, defaults, timing behavior, error reporting, persistent settings, installation prerequisites and recovery constraints. Include removed behavior as well as added behavior.

Do not publish an internal refactor as a customer benefit unless its effect is evidenced. “Improved reliability” is not a useful substitute for naming the corrected trigger and the release scope in which it was verified.

NASA’s product-transition guidance, section 5.5, includes operational and installation documentation. The original mapping below turns that general handover need into a concrete release-note review.

2. Build a change-to-action map

Changed behavior	Affected reader	Action question	Evidence needed
Configuration default	Site integrator	Does an existing explicit value remain valid?	Migration/default behavior for supported origins
Field interpretation	Protocol consumer	Must parsing or display logic change?	Versioned interface examples
Installation prerequisite	Update operator	Which starting states may use this package?	Approved transition and eligibility rules
Diagnostic behavior	Maintainer	Will alerts or support collection need adjustment?	New symptom and collection interpretation
Known limitation	Responsible operator	Is the intended use inside the assessed scope?	Bounded limitation and escalation route

One change can create several entries. A new status code may affect firmware integration, a user-facing message and an automated monitoring rule. Conversely, many commits may support one externally visible change.

3. Assign a clear action class

Use project-defined classes such as required before installation, required after installation, review before deciding, informational and no user action. Define their meanings and avoid treating a warning icon as the entire instruction.

A “no action” entry should still identify its scope. It may be true for installations using default settings while sites with an explicit override need review. If that difference is unknown, the note should identify the unresolved applicability question rather than invent a universal instruction.

For required actions, name the responsible role and point to the actual approved procedure. Release notes should not introduce an unreviewed command, suggest clearing persistent data by default or encourage bypassing eligibility or security checks.

4. Keep human guidance consistent with machine gates

RFC 9124 section 3.17 treats manifest text as human information rather than a basis for the recipient’s processing decisions. Its class and required-version elements address different machine-readable concerns. This is the RFC’s information-model boundary, not a claim that every embedded updater implements it.

The practical review is to compare the note’s stated applicability with the actual package and updater policy. A sentence saying “for all units” cannot extend a restricted package’s compatibility. Nor should an operator be told to override a rejection because the prose sounds broader.

If the human and machine descriptions disagree, hold the affected instruction and investigate the discrepancy. Correct the authoritative records through their normal review path; do not use release-note editing to conceal a packaging error.

5. Draft a fictional entry with an observable outcome

Imagine a noncritical telemetry product whose new release distinguishes an unavailable sample from a numeric zero. The fictional interface revision already defines the new status field and has its own approved examples.

A weak note says “improved data handling.” A useful draft says that integrators consuming the named interface revision must review unavailable-sample handling before adopting the release, preserve the defined validity state and verify the supplied unavailable-sample example in their own integration.

The entry should identify affected starting versions, the controlled interface reference and the evidence supporting the release’s implementation. It should not claim that every downstream application has been tested. No specific encoding or real product behavior is prescribed by this hypothetical example.

6. Review instructions from the receiver’s position

Ask a reviewer who did not implement the change to answer four questions from the note alone: does this affect my configuration, what must happen first, how do I know the action succeeded and what should I do if the observation differs?

Record missing information instead of allowing the author to fill it verbally. A link that only the development team can open is not an adequate receiving-party reference. Verify authorized access before distribution, without placing credentials or confidential debug data in the note.

Where an action can affect retained settings, name the approved preservation and recovery procedure. State unresolved rollback or migration limits honestly. Do not turn “recovery procedure exists” into a guarantee that every deployment can be restored without loss.

7. Publish only supported claims through the approved channel

Review check	Release-note acceptance question
Identity	Does this text name the exact release and applicable configurations?
Traceability	Can each externally visible claim be traced to reviewed evidence?
Action	Are prerequisites, responsible role and expected observations clear?
Limits	Are unresolved issues and unsupported combinations visible?
Authority	Has the designated owner approved distribution and commitments?

Keep a revision history if the notes themselves change. A corrected warning may matter even when the firmware bytes are unchanged. Identify what changed in the guidance and which recipients need the correction through the authorized communication process.

The finished result is a compact operational decision aid backed by the release evidence. It helps readers take the right next step without inventing benefits, implying tested customer environments or making support and delivery promises that nobody approved.