Skip to main content

Release notes

A release collects reviewed changes. When it is approved, ReleaseFlow writes one note for every audience in every release note language; when it is published, those notes are frozen.

Audiences​

Every approved release gets one release note per audience. Administrators manage audiences on the Audiences page or through /api/audiences. Each Organization starts with four presets, named in its output language (English or Vietnamese):

CodeWrites forTemplateFooter
operatoroperational risk, rollback, and how the product is deployed and runthe headline with the pull request link and narrative, then why, detail, limitations, and the migration step under its kindthe compare link and the upgrade guide
contributorimplementation detail and code changesas operator, with implementation instead of detailas operator
end_userplain language, what people noticethe headline and the narrative, and a migration step only when it is requirednone
supportwhat customers may ask about, and what to tell themthe headline with the link and narrative, the migration step under its kind, and limitationsnone

The audience list: four presets, the added Database administrators audience, and the added Support team audience marked Retired

An audience has a code (lowercase letters, digits, and underscores, starting with a letter; fixed once created), a display name, a communication intent that the AI follows when it writes the audience's narrative, a template for each change, and a footer for the note. Each preset's intent ends by saying when a change is none of its audience's concern: for end users, build, CI, dependency, test, and internal changes they cannot see. The operator intent asks for something to watch after deploying only when the change or the Project context names one. Templates are Mustache and render one change as Markdown with the variables whatChanged, whyChanged, technicalDetail, migrationStep, migrationKind, limitations, narrative, headline, relevance, brief, reference, pullRequestNumber, pullRequestUrl, and linkedIssues — a list whose items have key, title, type, status, recordedStatus, statusAtReview, and url, escaped like any other tracker text (Linked issues). status is the issue's status as of the release's review, or the one recorded with the change when the issue could not be read again; recordedStatus is the one recorded with the change, and statusAtReview the one read at review, empty when it was not read. A status that is not finished, or that ReleaseFlow cannot tell is finished, is empty in all three unless a person chose to show it (see Linked issues at review), so print it inside a section: {{#status}} ({{status}}){{/status}}. migrationKind is required, conditional, recommended, or unspecified for a step recorded before kinds existed, and is empty without a step (see AI classification). Since Mustache cannot compare values, the sections migrationRequired, migrationConditional, migrationRecommended, and migrationUnspecified are each true for one kind. headline is the audience's one-line headline, or whatChanged when it has none, so it always has a value; relevance is brief or full, and the section brief is true for a brief change (see What each audience reads). The summary values, headline, and narrative keep their Markdown, but any raw HTML in them is escaped, so a placeholder such as <id> shows as written wherever the note is read. reference is how the change's source names it: #12 for a GitHub pull request, !12 for a GitLab merge request, and the issue key, such as APP-12 or ENG-12, for Jira and Linear; pullRequestNumber is the bare number whatever the source. A section such as {{#narrative}} — {{.}}{{/narrative}} disappears when the value is empty. Preview renders a sample change. A template is checked when it is saved: it must compile, use only these variables, and use {{narrative}} rather than naming another audience.

The shipped templates lead with **{{headline}}**, and the detailed ones link a change as [{{reference}}]({{pullRequestUrl}}). The operator, contributor, and support templates print a change's limitations on a line of their own, Limitations (Giới hạn), so what a change does not do yet is not lost in its detail; the end-user template does not print them. They label a migration step by its kind: Required step, If it applies to you, Recommended step, or the neutral Migration for an unspecified one, so a step nobody called required is never presented as one. Their detail lines sit inside {{^brief}}, so a brief change keeps its headline, its narrative, and a required step, which is printed whatever the relevance. Audiences created before these templates keep their own until a preset is reset, and an Organization created before the support preset can add an audience coded support and reset it to the preset.

What each audience reads​

For each audience, the AI says how much a change concerns it: none (this reader would neither notice nor need it), brief (its headline is enough), or full. It also writes a headline, one line of at most 20 words, beside the narrative. A headline that is longer, runs over several lines, or remarks on missing evidence is dropped, and so is any sentence of a narrative that remarks on it ("not provided", "not specified"). An unknown relevance reads as full.

A note leaves out a change that is none for its audience, unless the change is breaking: a breaking change is in every note, and none on it reads as brief. A change with no narrative for the audience (no AI, a failure, or an audience added later) is included in full.

A security change is listed under 🔒 Security, after the breaking changes, whatever its category: a security fix is still a Fix everywhere else. A change that is both breaking and security is listed once, under breaking changes, and starts with 🔒 Security: whatever the audience's template prints. A security change is in the operator, contributor, and support notes even when it is none for them, and then reads as brief; for an end-user or a custom audience it follows its relevance like any other change, unless it is also breaking. See ADR-0037.

An operator note: the breaking-change warning links the upgrade guide, then the breaking change and the 🔒 Security section

The counts and the breaking-change warning describe what the note shows, and every change counts once, in the section it is listed in. An audience that nothing in the release concerns still gets its note: the title, the release summary, and one line saying that nothing in the release concerns it. Approval still writes one note per audience and language, and publication still needs every note. An automation action does not deliver such a note: it is skipped with nothing_for_audience, unless a person edited the note, which is then delivered as written. See ADR-0035.

The preview of a release&#39;s note for the Database administrators audience, which nothing in the release concerns: the title, the release summary, and one line saying so

An audience&#39;s template and footer in the editor, and its preview: a sample change followed by the footer

An audience's footer is a Mustache template rendered once, after the last section of the note (or after the line saying nothing concerns the audience), from the release's own values rather than a change's:

VariableValue
versionthe release's version
previousVersionthe version of the previous release, or empty
compareUrlthe code host's comparison of the previous version with this one, or empty
upgradeGuideUrlthe release's upgrade guide, or empty
releaseUrlthe code host's page for this version, or empty

An empty value is false, so a line inside {{#compareUrl}}…{{/compareUrl}} disappears when the release has no comparison, and {{^previousVersion}}…{{/previousVersion}} shows only for a first release. Inside a section, {{.}} is the section's own value and every other footer variable still has its value. A footer uses only these five variables; a change's variables, such as whatChanged, are not in it, and the footer's are not in an item template. A blank footer adds nothing. A footer is checked when it is saved, like a template, and Preview renders the sample change followed by a sample footer.

compareUrl and releaseUrl come from the Project's one code host, from the coordinates it was connected with; ReleaseFlow never asks the provider, so rendering a footer never calls the network, and a link can name a tag that does not exist yet.

SourcecompareUrlreleaseUrl
GitHubhttps://github.com/{owner}/{repository}/compare/{previousVersion}...{version}https://github.com/{owner}/{repository}/releases/tag/{version}
GitLab{GitLab URL}/{project path}/-/compare/{previousVersion}...{version}{GitLab URL}/{project path}/-/releases/{version}

A Project with no GitHub or GitLab source, or with more than one, gets neither link; Linear and Jira sources do not count. compareUrl is empty without a previous release. Each release's version is used, exactly as written, as its tag name: ReleaseFlow does not add or remove a v, and there is no tag-prefix setting. When a Project's tags are not its versions (v1.2.0 tags for 1.2.0 versions, or a server/ prefix), write the links in the footer by hand instead of using these two variables.

The operator and contributor footers show two lines, each only when it has its link: Compare (So sánh) links previousVersion...version to the comparison, and Upgrade guide (Hướng dẫn nâng cấp) links Read before upgrading to the guide. Neither links releaseUrl: a published note is often the GitHub release itself, where an install link would point to the page it is on. A note keeps the footer it was approved with, like its template.

The end of the same operator note: its footer links the upgrade guide

Upgrading custom audience templates​

Audiences created before 1.1.0 keep their own templates; nothing rewrites them. The shipped operator and contributor audiences received the new footer in each of their languages, since they had none, and the end-user and support audiences keep a blank one. A custom audience, such as a DBA audience, starts with a blank footer. To give one the limitations line and the footer, add this line inside its item template, where its other detail lines are (inside {{^brief}} if it has one):

text
{{#limitations}}
- Limitations: {{.}}
{{/limitations}}

and write its footer, on the Audiences page or through footerTemplateBody:

text
{{#compareUrl}}
**Compare:** [{{previousVersion}}...{{version}}]({{compareUrl}})
{{/compareUrl}}

{{#upgradeGuideUrl}}
**Upgrade guide:** [Read before upgrading]({{upgradeGuideUrl}})
{{/upgradeGuideUrl}}

For a Vietnamese template, the labels are Giới hạn, So sánh, Hướng dẫn nâng cấp, and Đọc trước khi nâng cấp. A release note language other than the main one has its own template and footer under Language templates. Reset to preset gives a shipped audience its shipped footer in every language.

Since 1.2.0, a linked issue's {{status}} is its status as of the release's review, and it is empty for an issue that is still open unless a person chose to show it. A template that prints ({{status}}) bare then prints (). Wrap it in a section so that an empty status prints nothing. A DBA audience's line, before:

text
- Tracked in [{{key}}]({{url}}): {{title}} ({{status}})

and after:

text
- Tracked in [{{key}}]({{url}}): {{title}}{{#status}} ({{status}}){{/status}}

Do the same in each language template (Theo dõi tại in Vietnamese). The shipped audiences print no linked issue, so none of them changes.

An Organization keeps between 1 and 20 audiences. An audience cannot be deleted while something still names it: a release note, an automation rule's action, or an automation run's history. A rule that is enabled or disabled can be pointed at another audience first. An archived rule cannot be changed, and run history keeps the audience it delivered to, so either keeps the audience for good; a refusal says which of these holds it. A preset can be reset to its shipped version in the current output language, and so can an audience your team added under a shipped code (operator, contributor, end_user, or support), which becomes a preset from then on. See ADR-0011.

Retiring an audience​

An audience nobody writes for any more can be retired instead of deleted, which works even while notes, rules, or runs name it. Open it on the Audiences page and choose Retire audience; the list then marks it Retired and says who retired it and when. From the next approval a retired audience gets no note, the AI is not asked for its narrative, and nothing is translated for it. Everything it already has stays: its templates, its footer, the narratives its changes carry, and every note written for it, which still opens and downloads. A release approved before the retirement keeps its note for the audience until it is approved again. The retirement confirmation lists the enabled automation rules that deliver the audience: their action for it is skipped rather than failed, and enabling a rule that delivers a retired audience is refused.

An audience&#39;s Manage audience card with Retire audience open: what retiring does, the enabled rule that delivers it, and Retire this audience

A retired audience&#39;s card: who retired it and when, that it gets no note, narrative or translation, and Bring back

Bring back makes it active again, and the page says who brought it back and when. A change the AI classified while the audience was retired has no narrative for it; its note still includes the change under the neutral headline (whatChanged), with no narrative, and never leaves it out. The release's Review tab lists those changes under Changes with no narrative for an audience, so a person writes the narrative with Edit summary, or asks the AI for only the missing narratives. The button shows the request's rough size in tokens, worked out from its text without sending anything; the answer adds those narratives and changes nothing else about the change. Through the API, a release in review or approved lists them as missingNarratives (changeId, reference, title, audienceNames, estimatedTokens), and any member asks the AI with POST /api/projects/{projectId}/changes/{changeId}/missing-narratives, which answers the change. A change the AI did not classify is refused with 409 change_not_eligible_for_ai; without AI the answer is 503 ai_classification_unavailable, and a failed request 502 ai_classification_failed, which records nothing.

Changes with no narrative for an audience on a release&#39;s Review tab: two changes with no narrative for the audience brought back, each with Ask the AI and its estimate in tokens

The preview of a brought-back audience&#39;s note before its narratives exist: each change under its neutral summary in bold

An Organization always keeps at least one active audience: retiring the last one is refused, and so is deleting the last active one. Every retirement and return is recorded with the administrator's name at the time. See ADR-0044.

Every audience endpoint is for administrators only:

text
GET /api/audiences
POST /api/audiences {"code", "displayName", "communicationIntent", "templateBody", "footerTemplateBody"}
GET /api/audiences/{audienceId}
PUT /api/audiences/{audienceId} {"displayName", "communicationIntent", "templateBody", "footerTemplateBody"}
PUT /api/audiences/{audienceId}/templates/{language} {"templateBody", "footerTemplateBody"}
DELETE /api/audiences/{audienceId}
POST /api/audiences/{audienceId}/retire
POST /api/audiences/{audienceId}/restore
POST /api/audiences/{audienceId}/reset-to-preset
POST /api/audiences/preview {"templateBody", "footerTemplateBody"} -> {"markdown", "html"}

An audience returns footerTemplateBody beside templateBody, and footerTemplateVariants beside templateVariants, each keyed by language. A request that leaves footerTemplateBody out keeps the footer the audience or language has, and a new audience then has none, so callers written before footers keep working. An audience also returns retiredAt and retirerName, both null while it is active.

SituationResponse
A member, not an administrator403
A missing field, or a code that is not [a-z][a-z0-9_]*400 validation_failed
A template or footer that does not compile or uses an unknown variable400 template_invalid
A template naming narratives.<code>400 template_narratives_path
The code is already used409 audience_code_taken
The Organization already has 20 audiences409 audience_limit
Deleting the last active audience409 audience_last
Retiring the last active audience409 audience_last_active
Retiring an audience that is retired, or bringing back one that is not409 audience_already_retired, 409 audience_not_retired
Deleting an audience that has release notes, that an automation rule's action delivers to (enabled, disabled, or archived), or that a run's history names409 audience_in_use; detail says which
Resetting an audience whose code no shipped audience has409 audience_not_preset
A language template for a language that is not a release note language400 template_language_not_targeted
An unknown or foreign audience404 audience_not_found

Release note languages​

By default every note is written in the Organization's output language. An administrator can choose up to five release note languages at the top of the Audiences page, or with PUT /api/organization/release-languages and {"targetLanguages": ["en", "vi"]}; every member can read them with GET. Tags are canonicalized and repeats dropped; an empty list, more than five, or an invalid tag returns 400 invalid_release_languages. Approving a release then writes one note per audience and language, so four audiences in English and Vietnamese make eight notes.

Each audience has its own template for every release note language that the output language does not cover, created when the language or the audience is added: a shipped audience starts from its shipped template in that language, with translated labels, and any other audience from a copy of its main template. Edit them under Language templates on the audience's page or with PUT /api/audiences/{audienceId}/templates/{language}. Resetting a shipped audience resets these templates too.

A change's summary, headlines, and narratives are written in the language the AI (or a person) used; a relevance is not text and is never translated. For a note in another language they are translated with DeepL after approval, never inside it:

sh
export RELEASEFLOW_TRANSLATION_PROVIDER=deepl # the default is disabled
export RELEASEFLOW_DEEPL_API_KEY=... # a key ending in :fx uses the free API
# RELEASEFLOW_DEEPL_BASE_URL overrides the host chosen from the key.

Translations are queued per change and language, and a background worker sends them to DeepL in batches. A translated text is cached for the Organization, so the same text is never sent twice, and an unchanged summary is never translated again, even when a release returns to draft and is approved again. A rate limit, a server error, or a network failure is retried up to five times with growing delays; any other failure is final. A pull request title used in place of a missing summary is not translated.

DeepL also receives the Project's context as its context, which guides the translation and is neither translated nor billed. It is part of what a translation is cached by: editing it translates again at the next approval, and an unchanged context still never sends the same text twice.

The release's own summary, the line under the note's heading, is translated the same way. A person writes it, in the Organization's output language, so a note in that language prints it as written and a note in any other language waits for its translation like a change's content. The translation never replaces what was typed: the release keeps its summary, and only the note in the other language reads the translated text. A release with no summary has nothing to translate.

Until its translations are in, a note shows the untranslated text and is Translating; the release page updates by itself when they arrive. A note whose translation failed, or that needs translation while the provider is disabled, is Not translated. Retry translations starts the failed ones over, and editing such a note by hand makes it ready. A release is published only when every note is ready: otherwise publishing returns 409 translations_not_ready, and the database refuses it as well. Editing a summary after approval translates the new text. See ADR-0015.

Seconds after approving v1.3.0: the Vietnamese Contributor note is Translating and still shows the untranslated summary, while the release details name v1.2.0 as the previous release and no upgrade guide

The same note once its translations arrived: the release summary and every change are in Vietnamese, and the glossary was Sent with every translation

text
GET /api/organization/release-languages
PUT /api/organization/release-languages {"targetLanguages"}
POST /api/projects/{projectId}/releases/{releaseId}/translations/retry

Glossary​

Machine translation turns product terms into words that mean something else: without help, DeepL wrote dbvault's "console" as giao diện dòng lệnh (command-line interface), "image" as hình ảnh (picture), and "pull request" as yêu cầu kéo. The Organization's glossary, on the Glossary page, fixes that for every note it translates. It holds two kinds of entry:

  • a kept term stays in English in every language: CLI, console, image, pull request. DeepL still writes the sentence around it and may adapt its form to the language, so dbvault's "images" came back as các image: a kept term is not frozen text;
  • a fixed translation always becomes the same words between two languages, named by their primary language: en → vi, "storage" → lưu trữ. It wins over a kept term with the same text, for its two languages only.

Administrators edit it and every member can read it. Nothing is added on its own: the page offers a list of terms common in software release notes, and only the ones an administrator ticks are kept. A term is 1 to 100 characters on one line, the glossary holds at most 500 entries, and uniqueness is exact: "Image" and "image" are two entries. A lowercase entry usually keeps the capitalized word at the start of a sentence too, so add another form only for one DeepL still changes.

The Glossary page: the terms kept as written in every language, the fixed en → vi translations, and the DeepL sync state of the pair

A glossary steers DeepL; it does not bind every word. DeepL can still translate a kept term inside a longer phrase: with "image", "secret", and "container" kept, dbvault's notes still got "container images", "emulator image", and "repository secrets" translated, and once a sentence-initial "The console". When DeepL translates a term inside a phrase, add the phrase as its own kept term (container images, repository secrets).

Each language pair the Organization translates is one dictionary in a DeepL glossary, whose version is the hash of what is sent. Approval only records that a pair is wanted, and a background job syncs it to DeepL outside any transaction, retrying a rate limit, a server error, or a network failure up to five times. Translations of the pair wait for that sync, then carry the glossary beside the Project's context. Its version is part of what a translation is cached by, so:

  • an edit translates again at the next approval, including the release's own summary;
  • an edit that leaves the dictionary as it was, such as deleting a term and adding it back, translates nothing again;
  • an Organization with no glossary sends exactly the requests it sent before.

A glossary never holds up a release. A pair DeepL serves no glossary for, or whose sync failed, is translated without it, and for each language the release page says whether the glossary was Sent with every translation, is still being waited for, or was Not applied, and why: the pair is unsupported, the sync failed, or DeepL answered in the source language with the glossary. Sent with every translation means the glossary went with every translation into that language, not that DeepL kept every term; read the note, and add a phrase DeepL translated as its own kept term. Retry translations tries a failed sync again. The glossary never reaches the AI.

The notes of an approved release: the glossary was Sent with every translation into vi

A translation that comes back in its source language is not stored as one. For a Vietnamese note, a sentence with at least three words left to translate and no Vietnamese diacritic fails; for a language in another script, such as Japanese or Russian, a sentence with no character of that script fails. Kept terms, code, URLs, paths, and words like MongoDB are left out of the count. A failing answer is translated once more without the glossary, and if it fails again the note is Not translated, like any failed translation. Other Latin-script languages have no such check yet. See ADR-0036.

With a glossary, DeepL changes the letter case of some code-like words: <backup-id> came back as <BACKUP-id>, and dbvault-cli as dbvault-CLI. A translation therefore keeps the source's placeholders (<, a letter, then letters, digits, hyphens, or underscores, then >) and its hyphenated names written in lowercase as the source writes them: where a translation differs from one in letter case alone, the source's form is put back, and nothing else changes. A word the source writes in two cases is left as DeepL wrote it. This happens when a translation is recorded, from DeepL or from the cache, so a translation cached earlier is corrected at the next approval without a request, and nothing that is sent changes. A placeholder DeepL drops is left out and logged. See ADR-0040.

DeepL also translates the words inside a code span: under 1 s came back as dưới 1 giây. A code span tells the reader to type or look for exactly that text, so a translation keeps the source's spans too. A span whose text the source writes stays as it is; the spans DeepL translated get the source's text back, in order, when there are as many of them as source spans the translation lost. Otherwise they are left as DeepL wrote them and the count is logged. A text holding a fenced code block or a double-backtick span keeps its spans as written. If DeepL both reorders two spans and translates them, each gets the other's text; that is the known limit of pairing in order.

So write a name the reader must find as written, such as a field, a parameter, or a string the interface prints in English, in a code span: limit, not 'limit'. Text in quotes is translated like any other text, because quotes hold ordinary words as often as names.

text
GET /api/glossary
GET /api/glossary/suggestions
POST /api/glossary/kept-terms {"terms": ["console", "CLI"]}
DELETE /api/glossary/kept-terms/{termId}
POST /api/glossary/translations {"sourceLanguage", "targetLanguage", "sourceTerm", "targetTerm"}
DELETE /api/glossary/translations/{translationId}

POST /api/glossary/kept-terms adds every term or none. GET /api/glossary returns keptTerms, translations, entryLimit, and pairs: for each language pair the Organization translates, entryCount and a status of empty, not_synced, pending, synced, outdated (edited since its sync), unsupported, or failed with its error.

SituationResponse
A blank, overlong, or multi-line term, an unknown language, or the same language twice400 validation_failed
A term the glossary already has, kept or for that pair409 glossary_term_taken
More than 500 entries409 glossary_limit
An unknown or foreign entry404 glossary_term_not_found

DeepL API Free holds one glossary. Each Organization uses one glossary of the DeepL account, and an API Free account holds only as many as its plan allows, which was one when this was tested. On such a key, the first Organization to sync gets the glossary; every other Organization's sync fails at once with quota_exceeded (DeepL's 456, which is never retried), its release page says the glossary was not applied, and its notes are translated without one. ReleaseFlow never deletes a glossary in DeepL.

Releases​

Open Releases to prepare a Project's releases. The page creates a release with a version (up to 50 characters), an optional summary, an optional planned release time in UTC, an optional upgrade guide, and the previous release, and lists the Project's releases with status filters and counts. A Project can prepare several releases at once, and each change belongs to at most one release.

A Project&#39;s releases by status: four published, none in draft, review, or approval

The upgrade guide is an absolute http:// or https:// address of at most 2,000 characters, without a user name or password; a query and a fragment are allowed. When the release has breaking changes, the warning in every note links read the upgrade guide to it, and the footer may link it too. The previous release is a published release of the same Project that the notes compare this one with. A new release follows the Project's most recently published release unless a person chooses another or none; the choice stays when another release is published later. Both can be changed while the release is a draft.

A release moves through four steps, shown at the top of its page:

  1. Draft. Add changes that have finished processing, by hand or with Add all available. A change that still needs review can be added; the release's review settles it. A change an administrator excluded from releases is not offered. Edit the version and summary, remove changes, then Request review, which needs at least one change.
  2. In review. The change list is fixed except for rejections. On the Review tab, each change gets a decision: Approve as shown confirms its category, breaking flag, and security flag, Edit classification corrects them, and Reject removes the change from the release so it becomes available for another one. Approving and editing record the reviewer on the change itself, exactly like a review in the Change Inbox, with an optional note. An Unknown change must be edited. Approve release becomes available once every change has a decision. A change whose title is fewer than three words, once its Conventional Commit prefix and issue keys are removed (fix, update deps), is marked Needs a summary unless a person wrote its summary, or the AI wrote one from a description of at least ten words (HTML comments not counted) whose context it did not find insufficient. A title that short cannot stand alone in a note, and an AI given nothing else can only restate it, so approval waits until a person writes the summary.
  3. Approved. The approver and time are recorded, and a release note is written for every audience in every release note language from its template (see Release note languages). Check each note's tab, edit a note's Markdown if needed (the note becomes Manual and no longer follows its template), then Publish release.
  4. Published. See Publishing.

Creating v1.3.0 with a summary, no upgrade guide, and v1.2.0 as the previous release, adding every available change, and requesting review: 17 changes wait for a decision

Any member can take every step, so one person can prepare, review, approve, and publish the same release. ReleaseFlow records who reviewed each change, who approved, and who published, but it does not require two different people.

Linked issues at review​

Requesting review reads every issue linked to the release's changes again, from Jira or Linear, in the background: a status read when a change was recorded may be weeks old. The Review tab says while the read is running, and whether an issue could not be read. A read that fails is tried again after 2, 4, 8 … seconds, five attempts in all; an issue still unread keeps the status recorded with its change. Returning to draft and requesting review again reads every issue again.

A note shows an issue's status only when the issue is finished: Jira's Done category, or a Linear issue that is completed or canceled. An issue recorded before 1.2.0, or read from a tracker that did not say, counts as not finished. Under Linked issues still open, the Review tab lists each issue whose status is not finished while its change ships, with Show this status: a member who chooses it lets every note print that very status, and ReleaseFlow records who and when. The issue then moves to Open statuses the notes show, which lists, while the release is in review or approved, each issue whose open status a person accepted: its key, the status the notes print, who accepted it under the name they had then, and when. A later read that returns another status takes it off that list and asks again. The release's GET carries the same on each of its linkedIssues: key, status, open, accepted, accepterName, and acceptedAt; the notes print status when accepted is true. The warning never holds up approval or publication. Notes are written at approval from the statuses read by then; a read that finishes later writes again the notes that still follow their template, until the release is published.

A release in review whose linked issues were read again: DBV-53, linked from #69, is still In Progress, with Show this status

Open statuses the notes show: an issue still In Progress, accepted by an administrator with the time

Folding a tracker change into its code change​

A Jira or Linear change and the pull request that did the work are one piece of work, and should be one item in a note. While a release is in review, the Review tab suggests folding a tracker change into a code change of the same release when the code change lists the tracker change's key among its linked issues, or when a person confirmed the two as a possible duplicate. Each suggestion says which.

A suggestion is evidence only, and nothing is folded on its own. A member chooses:

  • Fold, and reject … from this release takes the tracker change out of the release as a review decision would, so it is available for another release.
  • Fold, and exclude … from releases (administrators) excludes the tracker change from every release, with a reason ReleaseFlow fills in, such as "OPS-7 is tracked by #30, which carries the release-note entry.", which can be edited. See Excluding a change from releases.
  • Not the same work dismisses the suggestion: both changes stay, and it is not offered again in this release.

Folding suggestions on a release&#39;s Review tab: six tracker changes, each to fold into the code change that names it or that a person confirmed as its duplicate; the one for OPS-17 says #67 would become security, and each offers Fold and reject, Not the same work, and Fold and exclude with a prefilled reason

Either fold keeps the issue as linked context of the code change, adding it from the tracker change when the code change did not list it yet; an issue added that way is read from its tracker as of this review, like the others. Either fold also keeps the work's flags: the code change becomes breaking or security when the tracker change is. The suggestion says so first, such as "Accepting marks #30 security, as OPS-7 is", and accepting records it as the review of the code change and as its decision in the release, which names the folded change. A code change still Unknown needs a category first: 400 invalid_fold_decision. Each suggestion is decided once, with who decided and when; a release returned to draft keeps its decisions. A pair with nothing that ties them is not suggested: reject or exclude the tracker change by hand.

#67 after OPS-17 was folded into it: its decision is Edited by dbvault Lead, and it was marked security when OPS-17 was folded in

text
POST /api/projects/{projectId}/releases/{releaseId}/linked-issues/acceptance
{"tracker": "JIRA" | "LINEAR", "key", "status"}
PUT /api/projects/{projectId}/releases/{releaseId}/folding-suggestions/{trackerChangeId}/decision
{"codeChangeId", "decision": "ACCEPT" | "DISMISS", "removal": "REJECT" | "EXCLUDE", "reason"}

Both answer with the release, whose linkedIssueRead is PENDING, RUNNING, SUCCEEDED, or FAILED (absent before review is requested), and which lists linkedIssues (each with tracker, key, recordedStatus, statusAtReview, read, status, open, accepted, accepterName, and acceptedAt), foldingSuggestions (each with addsBreaking and addsSecurity), and foldDecisions. A decision a fold made names the tracker change in foldedChangeId.

SituationResponse
Accepting a status other than the one read last409 linked_issue_status_changed
Accepting a status of an issue no change of the release links404 linked_issue_not_found
Accepting a status while the release is a draft or published409 release_status_conflict
Deciding a suggestion that is not offered, or was decided404 folding_suggestion_not_found
Accepting without removal, excluding without a reason, or a fold that adds a flag to an Unknown change400 invalid_fold_decision
A member excluding403

Until it is published, a release can be scheduled or unscheduled, returned to draft (from review or approval, clearing its decisions and approval but not the reviews on its changes), or discarded (its changes become available again). Returning to draft also deletes the release notes; approving again writes new ones.

The planned release time of a release, in UTC

Before approval, the preview shows what each audience's note would say. A note starts with the release title and summary and a What's New overview with counts, warns about breaking changes, and lists breaking changes first, then security changes, features, fixes, performance, documentation, and maintenance, and ends with the audience's footer. Each change is written by the audience's template from its neutral summary and the audience's narrative; without a summary, the pull request title is used, with its Conventional Commit prefix removed. Labels are English or Vietnamese, following the output language.

A release&#39;s notes, one per audience and language; the operator note was edited by hand and is marked Manual

During review and after approval, Edit summary on the Review tab lets a person write or correct a change's summary, including its migration kind and limitations, and each audience's relevance, headline, and narrative. This works whether or not the AI wrote one, and the AI never replaces what a person chose. The form shows the active audiences only, and saving it keeps a retired audience's narrative as it was. Through the API, each audience's narrative is {"relevance": "NONE" | "BRIEF" | "FULL", "headline", "body"} or, as callers written before relevance existed send, a plain string, which is a full narrative without a headline. A full narrative with neither headline nor body is not kept, since it says no more than having none; an unknown relevance returns 400 malformed_request. A request that names no migrationKind, as callers written before it existed send, records UNSPECIFIED for a step and NONE without one; a kind that does not match the step (NONE with a step, any other without) returns 400 validation_failed. A narrative for a retired audience that the request leaves out is kept. The change records who wrote it, and the notes of an approved release that still follow their template are rendered again. Notes reflect the changes at approval: to pick up a classification corrected later in the Change Inbox, return the release to draft and approve it again. See ADR-0010 and ADR-0011.

Edit summary on a release&#39;s Review tab: the migration kind and limitations, then each audience&#39;s relevance, headline, and narrative

REST clients use the same rules:

text
GET /api/projects/{projectId}/releases
POST /api/projects/{projectId}/releases {"version", "summary", "plannedReleaseAt",
"upgradeGuideUrl", "previousReleaseId"}
GET /api/projects/{projectId}/releases/{releaseId}
PUT /api/projects/{projectId}/releases/{releaseId} {"version", "summary", "upgradeGuideUrl", "previousReleaseId"}
DELETE /api/projects/{projectId}/releases/{releaseId}
PUT /api/projects/{projectId}/releases/{releaseId}/schedule {"plannedReleaseAt"} (null clears it)
GET /api/projects/{projectId}/releases/{releaseId}/available-changes
POST /api/projects/{projectId}/releases/{releaseId}/changes {"changeIds": [...]} or {"allAvailable": true}
DELETE /api/projects/{projectId}/releases/{releaseId}/changes/{changeId} (remove, or reject during review)
POST /api/projects/{projectId}/releases/{releaseId}/request-review
PUT /api/projects/{projectId}/releases/{releaseId}/changes/{changeId}/decision
{"action": "APPROVE" | "EDIT", "category", "breaking", "security", "note"}
POST /api/projects/{projectId}/releases/{releaseId}/approve
POST /api/projects/{projectId}/releases/{releaseId}/return-to-draft
POST /api/projects/{projectId}/releases/{releaseId}/publish
POST /api/projects/{projectId}/releases/{releaseId}/translations/retry
PUT /api/projects/{projectId}/releases/{releaseId}/changes/{changeId}/summary
{"whatChanged", "whyChanged", "technicalDetail", "migrationStep",
"migrationKind", "limitations",
"narratives": {"<code>": {"relevance", "headline", "body"} or "..."}}
GET /api/projects/{projectId}/releases/{releaseId}/note-previews
GET /api/projects/{projectId}/releases/{releaseId}/notes
PUT /api/projects/{projectId}/releases/{releaseId}/notes/{noteId} {"content"}
GET /api/projects/{projectId}/releases/{releaseId}/notes/{noteId}/download
GET /api/projects/{projectId}/release-assignments

plannedReleaseAt is an ISO-8601 instant such as 2026-10-01T09:00:00Z; a value without an offset is read as UTC. A create request that leaves previousReleaseId out follows the most recently published release, and an update that leaves upgradeGuideUrl or previousReleaseId out keeps it; an explicit null clears either. A decision that leaves security out confirms the change's current flag, as callers written before it do; APPROVE must otherwise send the flag the change has. A release returns upgradeGuideUrl, previousReleaseId, previousVersion, its changes, its decisions (changeId, action, reviewerName, note, decidedAt), reviewedCount, plannedReleaseAt, approvedAt, approverName, and its notes (id, audienceCode, audienceName, language, content, autoRerender, lastEditorName, updatedAt, translationStatus: READY, PENDING, or FAILED, and glossaryStatus: NONE, PENDING, APPLIED, or NOT_APPLIED with a glossaryReason), and glossaries: one entry per note language whose pair has a glossary, with its language, status, and reason. The download is text/markdown, named <version>-<audience code>-<language>.md. release-assignments lists which release, by ID, version, and status, each of the Project's changes belongs to. Errors:

SituationResponse
The operation does not fit the release's status409 release_status_conflict
Review requested or approval attempted with no changes409 release_empty
Approval attempted before every change has a decision409 release_review_incomplete
Approval attempted while a change with a title of fewer than three words has no summary a person wrote, and too little description for the AI's; detail names them409 change_summary_required
APPROVE sent with a classification other than the change's current one, security flag included409 classification_changed
An upgrade guide that is not an absolute http:// or https:// address, has a user name or password, or is over 2,000 characters400 invalid_upgrade_guide_url
A previous release that is not a published release of this Project400 invalid_previous_release
unknown or an unsupported category in a decision400 invalid_change_review
APPROVE of an Unknown change, whatever category it names: approving keeps the current classification, so an Unknown change takes EDIT with a category400 invalid_change_review
An unreadable or past planned release time400 invalid_release_schedule
A change still processing or already in another release409 change_not_releasable
A change excluded from releases409 change_excluded
The version is already used in this Project409 release_version_taken
A summary or note edit outside the allowed status409 release_status_conflict
An audience template that cannot render at approval409 release_note_render_failed
Publishing an approved release that has no notes409 release_notes_missing
Publishing while a note is still translating or could not be translated409 translations_not_ready
An empty summary or note, or a field over its limit400 validation_failed
An unknown or foreign change404 change_not_found
An unknown or foreign release404 release_not_found
An unknown note of this release404 release_note_not_found

Publishing​

On an approved release's page, open Publish release. Publishing freezes every audience's note, together with who published the release and when. The page then becomes read-only. It shows who approved and published the release, and offers one tab per audience and language with the rendered note, its Markdown, a Copy button, and a Download link for GitHub Releases or a changelog. Downloaded files are named <version>-<audience>-<language>.md.

Publishing approved v1.3.0: it becomes Published, an immutable snapshot whose glossary went with every translation, and the Contributor note downloads as Markdown

A published release cannot be edited, scheduled, reviewed, discarded, unpublished, or changed in content, and neither can its notes. Its changes can still be corrected in the Change Inbox, but the published notes keep what was published. PostgreSQL triggers enforce this even for direct SQL. See ADR-0005 and ADR-0011.

REST clients call POST /api/projects/{projectId}/releases/{releaseId}/publish. It returns the release with status, publishedAt, publisherName, and notes. Until publication, preview groups the release's current changes into the note's sections; after it, preview is empty and the notes are in notes. markdown is null, except for a release published before Flyway V13. Publishing a release that is not approved returns 409 release_status_conflict; any operation on a published release returns 409 release_published.