Translation
Translated from the Spanish source, which is the normative text. Status: draft pending human review. Differences are resolved in the Spanish text.
description: Branches, environments and releases in SCAFFOLD 0.1: how to link work items to changes, promote the same artefact between environments and publish traceable releases.¶
Branches, environments and releases¶
This page explains how a project that declares SCAFFOLD 0.1 carries work from a planned item to a deployed release, and how it goes back from the release to the item. It is an explanation: the rule is in the requirements and this page adds no obligations. Branch names, tools and environments are fictional examples.
In brief¶
- Each branch and each integration request cites a work item or a batch (R-025).
- The main branch is protected; work branches are short-lived and belong to a single batch (R-026).
- Each environment has a purpose, a maximum admitted data value, an origin of secrets and who deploys (R-027).
- The same artefact is promoted, identified by its digest; configuration is injected separately (R-028).
- A release has a declared scheme, an immutable tag and notes obtained from its items (R-029).
Status: SCAFFOLD 0.1 is an accepted edition (level of recorded human decision). None of these practices is presented here as proven by our own measurements; anything said about savings, stability or security requires measurement (R-032).
From item to release, and back¶
The cycle has five links. Each one keeps the identifier of the previous one, so that a query can walk the chain in either direction.
| Link | What it keeps | How it is linked |
|---|---|---|
| Work item | Stable identifier, for example TIE-12 |
List of batches, branches, changes and release that implement it |
| Branch | Name with the identifier | feature/TIE-12-export-csv |
| Committed change | Message with the identifier and the attribution in a machine-readable field | Trailers at the end of the message |
| Integration request | Item or batch, branch, responsible person, assistants, checks and reviewer | Text of the request |
| Release | Immutable tag and release note | List of included items |
With those links, the technical owner can answer two questions: "which items does release 1.4.0 include?" and "which changes implement TIE-12?". The expected evidence of R-025 is a query that lists items per release; this page does not prescribe which tool runs it.
Branch naming convention¶
A fictional project, Ana's online shop, declares this pattern:
<type>/<identifier>-<short-summary>
feature/TIE-12-export-csv
fix/TIE-31-rounding-of-totals
The type matches the batch types of R-009. The
identifier is never reused (R-021). If the code-hosting
service or the team's file system does not accept certain characters, such as accents or slashes in
branch names, the project declares a variant (feature-TIE-12-export-csv); what matters is that the convention
is written down and that a query can extract the identifier.
Attribution in the change message¶
R-003 asks that each change be attributable to a responsible person
and, if one intervened, to the assistant that produced it. R-025 asks that this attribution be in a
machine-readable field. One option is to use git trailers: key: value lines at the end of the
message, after a blank line, which the tool
git-interpret-trailers (accessed
14 Oct 2026) can read and add.
Export orders to CSV with configurable separator
Refs: TIE-12
Batch: L-2026-014
Co-authored-by: code-assistant <code-assistant@example.invalid>
Responsible: Ana
Co-authored-by: is a widespread convention; it is not claimed that every hosting service
recognises it or displays it the same way. The keys Refs, Batch and Responsible are names in this
example; the project chooses its own and declares them. Residual risk (R-003): the declared attribution
may be false or incomplete; the trailer records a declaration, it does not verify it.
Branching model¶
R-026 asks the repository to declare its model: main branch, branch types, who integrates and with which checks. The model in the example:
| Element | Declaration in the example |
|---|---|
| Main branch | main, protected: it only receives changes through an integration request reviewed by a person |
| Work branches | feature/…, fix/…; declared maximum lifetime of 3 working days (fictional figure) |
| One branch per batch | The branch belongs to a single batch; a batch with several branches declares it |
| Who integrates | The technical owner or the person they designate. An assistant does not write to the main branch except through an integration request reviewed by a person; integrating what is catalogued as critical is decided by a person |
| Checks | The repository's own, before integrating (R-010) |
Two assistants do not write to the same branch at the same time, except under a declared turn. This relates to write zones (R-001), which divide paths, and to branches, which divide lines of history. They are two different maps: a branch can touch several zones (then the batch names their owners, R-002) and a zone can receive changes from several branches. One possible pattern is to give each assistant its own separate workspace (a distinct working copy or worktree of the same repository), so that its branch does not get mixed with another's. It is an organisational option; the requirement does not demand it and it does not by itself guarantee that there are no collisions.
Sources and differences¶
Trunk Based Development, "Short-Lived Feature Branches" (accessed 14 Oct 2026) describes feature branches that last “a couple of days” and are merged into the shared branch when closed. R-026 shares the preference for short branches (as a SHOULD, with a declared maximum lifetime), but does not adopt that technique in full: it adds protection of the main branch, human review and the rule of a single writer per branch. That SCAFFOLD and that source coincide on one point does not make them equivalent.
Checks before integrating¶
Before integrating a batch, the checks the repository declares are run (R-010). Fictional examples: automated tests, style analysis, a check that contract and code declare the same version (R-006) and the exclusion inventory of the engineering layer (see below). The definition of done includes these checks (R-023). An assistant does not integrate or deploy by itself whatever the project's catalogue of critical effects includes; everything else follows the declared checks. Residual risk: the checks and human review can miss errors.
Environments¶
An environment is a place where the software runs. R-027 asks to declare, for each one: purpose, maximum data classification, origin of its secrets, who may deploy and entry checks. Classification uses a scale with a name and defined values that the project declares (MILPA-R-003). Fictional scale in the example: public, internal, confidential, critical (from lowest to highest). Synthetic or anonymised data are a practice for test environments, not levels of the scale. Example table (fictional):
| Environment | Purpose | Maximum value admitted | Secrets | Who deploys |
|---|---|---|---|---|
| Local | Develop and test on the machine of whoever is working | Public (synthetic data) | Own to the environment, with no real value | Whoever is working, including their assistant |
| Integration | Run automated checks on each branch | Public (synthetic data) | Own, kept in the project's secrets store | The continuous integration process |
| Staging | Test the candidate release | Internal (anonymised data) | Own, different from production | Delivery owner |
| Production | Serve users | Critical | Own, accessible only to the deployment process | Delivery owner, with informed human confirmation |
Rules the table illustrates (R-027): an environment that uses secrets has its own, not shared with another environment; a non-production environment does not receive real data above its declared value except under a recorded exception; deploying to production appears in the catalogue of critical effects. That treatment comes from ASILO-R-005 (human review before critical effects) and the secrets from ASILO-R-006. Residual risk: a copy of data can leave its environment by an undeclared route.
Promoting the same artefact¶
R-028 separates three things: the artefact (what is built), its configuration (different per environment) and its deployment. What reaches production is the same artefact that passed the checks, identified by its cryptographic digest, without rebuilding it per environment. Configuration is injected separately at deployment.
- The artefact is built once and its digest is calculated.
- The checks run on that artefact, not on a rebuild.
- Each promotion records the digest; if it does not match the checked one, it is not promoted.
- Before deploying to production, a rollback plan exists.
- On deployment, version, digest, environment, the person who authorised it and the result are recorded.
A rollback (returning to a previous artefact) does not by itself undo data changes; this is the residual risk of R-028 and the plan mentions it where it applies. The format of the record is in the templates.
The source The Twelve-Factor App, "V. Build, release, run" (accessed 14 Oct 2026) separates build, release (build plus configuration) and run, and discourages changing code at run time. R-028 agrees on that separation, but adds the digest as identity, the rollback plan and the deployment record, which that source does not prescribe in those terms. SLSA (SLSA 1.2, the version the specification presents first on 14 Oct 2026; accessed that day, without citing sections) is a framework for supply-chain integrity and build provenance. SCAFFOLD does not require it; a project may adopt it as its own profile, and that adoption does not follow from following R-028.
Deployment to production as a critical effect¶
The project includes "deploy to production" in its catalogue of critical effects, which the charter records (R-019); R-027 requires it to be there. An assistant may prepare the artefact, propose the rollback plan and fill in the record; informed confirmation to deploy is given by a person, normally the delivery owner, and the record notes the person who authorised (R-028). Asking for confirmation only for what is catalogued is deliberate: ASILO-R-005 warns that asking for it for everything leads to approving without reading, and R-010 takes it up.
Releases¶
R-029 asks for four things, which the example declares as follows:
- Declared scheme. Ana's shop uses three numbers (major.minor.patch) and declares which change raises each one: incompatible with what is published, added feature, fix.
- Immutable tag. Each published release has a tag in version control and that tag is not moved to another change; if there is an error, a new release is published.
- Notes from the items. The release note is obtained from the work items included, not rewritten from memory (see the template).
- Incompatible changes flagged, and the person who authorised the release.
Sources, with their differences:
| Source | What it contributes | Difference from R-029 |
|---|---|---|
| Semantic Versioning 2.0.0 (accessed 14 Oct 2026) | A versioning scheme and rules for raising major, minor and patch | It is one possible scheme; R-029 only asks to declare one, whether this or another |
| Conventional Commits 1.0.0 (accessed 14 Oct 2026) | Convention for change messages with types that correspond to version bumps | R-025 asks for a machine-readable field for attribution; the message convention is a different, optional format |
| Keep a Changelog 1.1.0 (1.1.0, the version its page declares; accessed 14 Oct 2026) | Format of a change file written for people, per release | R-029 asks that notes be obtained from the work items; that format can serve as presentation, not as a source |
None of the three is mandatory. Choosing one does not show conformity with SCAFFOLD.
Urgency path¶
When a fix cannot wait for the normal checks, the urgency path is defined in advance, leaves a record when used and ends in a later review (R-013). It does not exempt the human review of ASILO-R-005, which is prior or, if the emergency exception defined in advance applies, later. The deployed artefact is the same one that passed the checks; if it is different, its digest and what was skipped are recorded (R-028) and the deployment enters the later review. Fictional example: the delivery owner authorises the deployment of a fix for TIE-40 with reduced tests; a person confirms the critical effect beforehand (or, if the emergency exception applies, reviews it afterwards); the same day an item is opened for the later review and the artefact digest is recorded along with which checks were skipped. Residual risk: the later review does not undo all the effects.
Exclusion of the engineering layer¶
Zones, handoff notes, batches and the configuration of the coding assistants belong to construction, not to the product. R-011 asks that they stay out of the deployed artefact, checked on the already built artefact. Example: after building, a check walks the contents of the artefact and fails if it finds the handoff notes folder. Residual risk: the inventory can miss files or embedded data. This check is part of entry to integration or of promotion, as the project decides.
Delivering a regional change¶
Fictional example: a work item updates a regional package used by a library. Its acceptance criteria can include correct reference and digest, technical compatibility and cases of uncovered scope, changed context and pending review. The project declares its checks; actual results are recorded before integration (R-010, R-023).
Delivery identifies the artefact, regional content and selected configuration. Under R-028, the promoted artefact retains its digest and environment configuration is injected separately. If regional content is a required runtime dependency, it belongs to the product according to its design; exclusion under R-011 concerns engineering-only configuration, such as zones, notes and assistant configuration, rather than all content called “context”.
For updates or rollback, retain relevant versions and references, compatibility criteria, results and the delivery decision. Rolling back a package does not itself reverse effects on data or put a previous legal source back into force. The plan explains those limits and the treatment of incompatible changes. Release notes relate to work under R-029; an incident or rollback retains the post-incident review in R-032. The shared guide distinguishes those records from legal applicability and authorization.
Measuring delivery¶
R-032 asks to declare which delivery indicators are measured, how and how often. It does not fix which. One option is the five DORA (accessed 14 Oct 2026) metrics: change lead time, deployment frequency, failed deployment recovery time, change fail rate and deployment rework rate. Choosing them does not prove improvement: R-032 requires measurement before and after to claim an improvement, and warns that an indicator can improve without the outcome improving. This page offers no reference figures.
Hypothesis and what would promote them¶
| Claim | State | Verification that would promote it |
|---|---|---|
| A pattern of separate workspaces per assistant reduces collisions between branches | Hypothesis (not measured) | Compare integration collisions before and after in a real project, with dated data |
| The branch name suffices to extract the identifier in the team's tools | Hypothesis (depends on the tool) | Run the R-025 query on a test repository |
Hosting services interpret Co-authored-by: uniformly |
Not claimed | Review the current documentation of each specific service |
Further reading: crews, templates and the SCAFFOLD page.