Release notes from merged changes

Use this workflow to turn merged pull requests, tickets and deployment notes into a release-note draft that customers can act on. It is for engineering, support and product teams preparing a software release. The result separates new behaviour, fixes, known limits and required user actions, with evidence for every statement.

1. Set the release boundary

Start with one named release and one cut-off time. Put this information at the top of the working document:

• Release name or number
• Target deployment date
• Environment, such as hosted service, self-managed package or mobile application
• Merged-change window, from the previous release cut-off to this release cut-off
• Audience, such as administrators, end users, API consumers or support teams
• Owner who can approve wording and scope

Do not collect every recently merged pull request without a boundary. That produces notes for work that may not ship.

Create four empty sections in the draft:

1. New behaviour
2. Fixes
3. Known limits
4. Actions required

Keep an Internal evidence section below them. Customers will not see it, but reviewers need it.

2. Collect the source records

Export or copy the records for changes that are both merged and intended to ship. For each item, collect the pull request, linked ticket, acceptance criteria, test result, deployment flag or configuration note, and any support issue it resolves.

Put one row per candidate change in a working table.

Field	What to record	Why it matters
Change ID	Pull request and ticket reference	Lets reviewers trace each claim
Customer group	Who sees the change	Prevents irrelevant notes
Before and after	Observable behaviour	Supplies plain-language wording
Rollout condition	Default, opt-in, staged or configuration-dependent	Stops overstatement
Evidence	Test, demo, incident or product decision	Supports the claim
Owner	Engineer, product manager or support lead	Gives reviewers a route for questions

Exclude routine refactoring, dependency updates and internal observability work unless they change customer behaviour. If a security-related change needs public wording, ask the designated security owner for the approved scope. Do not infer what can be disclosed from the pull request alone.

3. Classify each change before drafting

Assign each candidate to one primary release-note category. Classification comes before prose. It prevents the common mistake of describing a fix as a new feature or hiding a limitation in a vague sentence.

If the customer experiences this	Put it in	Drafting rule
A new screen, setting, endpoint or result	New behaviour	State who can use it and what changes
Existing behaviour now works as intended	Fixes	State the prior symptom, not internal cause
A supported task still fails or has a restriction	Known limits	State the condition and practical impact
A customer must change settings, process or integration	Actions required	Start with the action and deadline or condition

A single change can appear in two sections when that is necessary for accuracy. For example, a new setting may need an action item explaining how administrators enable it. Link the two statements in your internal evidence, rather than repeating a long explanation.

Use Not customer-facing for anything that does not belong in the published notes. Keep these rows until approval, so nobody has to rediscover why they were excluded.

4. Generate a first draft from evidence

Give the model only the release boundary, the classified table and the intended audience. Remove credentials, customer data, private incident details and unapproved security information first. Model behaviour and available features can vary, so check the current guidance in the xAI documentation overview.

Use a prompt that fixes the output structure:

Draft customer-facing release notes for [release name].
Audience: [audience].
Use only the evidence supplied below. Do not invent dates,
compatibility claims, performance claims, causes or workarounds.

Create these sections in this order:
1. New behaviour
2. Fixes
3. Known limits
4. Actions required

For each item, write one short heading and one or two sentences.
Name the affected user, setting, workflow or API behaviour where known.
If evidence is incomplete, write: NEEDS CONFIRMATION.

Evidence:
[paste classified rows]

Ask for one release rather than a combined quarterly list. A smaller, bounded input makes it easier to trace each sentence back to a source record.

Write in present tense for behaviour available after release. Say Administrators can now... rather than We have implemented.... For fixes, say what users should no longer see: Fixed an error that prevented CSV exports when a report contained empty values. Do not promise that every case is resolved unless the evidence supports that claim.

5. Review every sentence against the source

Read the draft alongside the working table. Check claims, not just grammar. A polished sentence can still be wrong because it covers too many users, misses an activation step or converts a test result into a guarantee.

For each published item, answer these questions:

• Can you point to one source record that supports it?
• Does it name the affected user, product area or integration accurately?
• Does it say whether the behaviour is automatic, opt-in or configuration-dependent?
• Is a required action visible in Actions required, rather than buried in another section?
• Does a known limit describe the trigger and customer impact?
• Has any internal detail, customer identifier or unapproved security information been removed?

Signs the output is wrong

Treat these as defects requiring a rewrite or confirmation:

What you see	Likely problem	What to do
Improved performance with no defined user effect	Unsupported broad claim	Replace it with observed behaviour or remove it
All users can when rollout is staged	Scope is overstated	Name the eligible group and rollout condition
A fix with no description of the former symptom	Internal wording leaked through	Describe what the customer previously could not do
A limitation hidden after a feature announcement	Material condition is missing	Add a separate known-limit item
An action without a setting, owner or timing condition	Customer cannot complete it	Add the exact configuration or ask the owner

6. Approve and hand over the release-note pack

Send the draft and internal evidence table to the release owner, product owner and support lead. Give each person a specific review task:

• Engineering confirms technical accuracy, rollout state and affected components.
• Product confirms customer relevance, terminology and whether exclusions are acceptable.
• Support confirms that fixes and limits match customer language, and prepares responses for likely questions.

Record approval beside each item, not only at document level. Then create the publishing pack:

1. Approved customer-facing release notes.
2. Internal evidence table with source links or references.
3. Support brief listing known limits, required actions and approved troubleshooting wording.
4. Deferred-items list for changes that merged but did not ship.

When the workflow does not work

If the draft is too vague, the input table lacks before-and-after behaviour. Return those rows to the change owner and request one customer-visible example. If the draft contains unsupported detail, reduce the input to approved evidence and require the model to preserve NEEDS CONFIRMATION markers. If reviewers disagree on whether a change shipped, pause that item, check the deployment decision and publish it in a later note if necessary.

If the release is too large to review safely, split the work by product area, then run the same classification and approval steps for each area. Combine only approved items into the final document.