← Back to the learning library
Before you begin: Basic repository, commit and build concepts; no particular branching model is assumed.
Reading time and practice time are estimates. Examples use fictional products and illustrative engineering values, not approved product limits.
Learning objectives
By the end of this module, you should be able to:
- Identify configuration items beyond source code.
- Apply proportionate branching, review and change control.
- Create unambiguous firmware identification and compatibility rules.
- Establish a reproducible release baseline.
Lesson 1
1. The product is more than the repository
A firmware binary depends on source, build scripts, compiler and linker versions, libraries, generated code, board definitions, feature flags, calibration defaults and security material. Treat the controlled inputs needed to reproduce and understand a release as configuration items.
Generated files should either be reproducibly generated or controlled with their generator and input. “The build server has the right tool” is not a configuration record.
Lesson 2
2. Version control supports review and traceability
Keep changes small enough to review, link them to an authorised purpose and require appropriate approval before merging. Choose a branching approach that matches release frequency and team size; the objective is controlled integration, not adherence to a fashionable model.
Tags should be immutable and protected. A release tag must resolve to the exact source used for the delivered binary.
Lesson 3
3. Version identity must answer compatibility questions
A version shown to service personnel should uniquely identify the installed firmware. Where bootloader, application, radio stack, configuration and hardware can change independently, define a compatibility matrix or machine-readable rule. Semantic versioning alone does not solve product compatibility.
Embed a build identifier that can be read through the device interface and connected to the release record.
Lesson 4
4. Reproducibility needs a defined level
Byte-for-byte reproducibility is valuable but may be affected by timestamps, paths or nondeterministic tools. At minimum, retain the released binary, hash, controlled inputs, tool versions and build log. If a build cannot be reproduced exactly, document how equivalence would be established.
Lesson 5
5. Distinguish source, build and installed identity
A source commit identifies repository content but not necessarily the compiler, external libraries, build flags or signing operation. A binary hash identifies bytes but cannot explain their origin. A service version is useful to people but may cover several variants. Preserve all three relationships in a release manifest.
| Manifest field | Illustrative value / purpose |
|---|---|
| Product and variant | Controller B, production, supported board revisions B2–B4. |
| Build inputs | Full source revision, dependency locks and generator inputs. |
| Tool environment | Compiler/linker versions, tool digests and build command. |
| Output identity | Unsigned and signed image hashes with signature metadata. |
| Compatibility | Bootloader minimum, schema version and allowed peripherals. |
| Approval evidence | Verification summary, open anomalies and release authority. |
Calibration values and device identity may differ legitimately per unit. Keep them distinct from the common image, but identify their schema, permitted ranges, provisioning authority and backup/restore rules.
Lesson 6
6. Control variants and maintenance branches
A feature flag is a product decision when it changes safety, performance, connectivity or memory behaviour. Maintain a supported-variant matrix and reject undocumented combinations. Configuration options multiply: ten independent booleans theoretically permit 1,024 combinations. Do not claim to support all of them because the build system accepts them.
Maintenance branches need an owner, supported lifetime, dependency policy and backport criteria. A security fix applied to main may need adaptation and separate verification on an older branch. Record the link between the original issue and each branch-specific change, then update the inventory of affected field versions.
Protect baseline identity while allowing controlled corrections. If release documentation contains an error, revise the record with history; do not silently move the source tag or replace the binary under the same identifier.
Lesson 7
7. Demonstrate reproducibility and impact
Perform a clean build away from the original developer environment. Compare outputs and investigate differences such as embedded timestamps, absolute paths, archive ordering or generated identifiers. Reproducible construction does not establish functional correctness; it establishes a controlled connection between inputs and outputs.
For a toolchain upgrade, review code-generation changes, diagnostics, linker layout, library behaviour, debug information and affected qualification arguments. Re-run targeted timing and integration tests as well as host tests. A compiler patch can change machine code without changing source requirements.
Retain the released image even when reproducibility is excellent. Field investigation should begin from what actually shipped, including signatures and packaging, not an approximation rebuilt from a remembered command.
Decision guide
What should a release baseline contain?
| Item | Why it matters | Typical control |
|---|---|---|
| Source and submodules | Defines implemented logic. | Protected release tag and commit identifiers. |
| Toolchain and dependencies | Can change generated machine code. | Locked versions, checksums and retained installer/container. |
| Configuration and generated inputs | Changes features and target behaviour. | Reviewed files tied to product variant. |
| Binary and hash | Identifies what was actually delivered. | Immutable release repository. |
Worked example
Worked example — one codebase, three board revisions
The same application supports boards A, B and C with different pin maps and sensor drivers.
Board selection is a reviewed build-time configuration, not a compiler flag entered manually. Each board definition has a hardware compatibility identifier. CI builds every supported variant from the release tag and produces a manifest containing source commit, toolchain, dependencies, configuration, binary hash and test results.
A field binary can be traced to its exact inputs, and an incompatible board image is rejected before installation.
Engineering evidence
What should the work produce?
Configuration-management plan
Defines items, identifiers, baselines and authorities.
Versioning and compatibility scheme
Explains product and component identity.
Build manifest
Captures inputs, toolchain, variant and binary hash.
Release record
Links approval, tests, anomalies and delivered artefacts.
Common failure patterns
What goes wrong?
- Versioning only the application while ignoring bootloader and configuration.
- Rebuilding a release later instead of retaining the delivered binary.
- Uncontrolled local compiler or feature flags.
- Moving or recreating release tags.
Applied exercise · approximately 25 minutes
Reconstruct an ambiguous field release
A device reports 2.4.0. Two binaries share that version: one for board B and one for C. A developer rebuilt the C image after a compiler patch but retained the release name.
- List the records needed to identify what each field device actually runs.
- Define a revised version/variant scheme and a release-manifest minimum.
- Specify a correction process that preserves the original release history.
Review a suggested approach
Read a binary/build identifier and board identity through a controlled service interface where available, then compare against retained artefacts and installation records. If that information was never recorded, state the uncertainty rather than inventing provenance. A field retrieval or controlled replacement may be necessary.
Keep a human-readable release plus an unambiguous build and variant ID tied to a hash. Record the compiler patch as a new controlled build with its own verification and approval. Preserve both previous files and explain the naming error in a corrected release record; do not rewrite history to make the ambiguity disappear.
Completion criteria
- Human version, build identity and board compatibility are distinguished.
- Uncertain field configuration is treated as an investigation, not assumed away.
- The revised process preserves delivered binaries and approval history.
This is a self-directed engineering exercise, not an accredited examination. Compare the rationale as well as the final answer.
Practical check
Questions for your next design review
- Can the exact field binary be identified from the device?
- Are all build-affecting inputs controlled?
- Does each released binary have a cryptographic hash?
- Are supported component and hardware combinations defined?
- Could another engineer reconstruct the release evidence?
Configuration control turns “this code” into an identifiable, supportable product release.
References and further reading
Educational guidance only. Apply the authorised standards editions, regulations and approved procedures relevant to your product and market. Linked publications support further study; the fictional exercises do not demonstrate compliance.