Release Notes¶

Release notes are product communication, not a commit log. They explain shipped impact in terms a user, operator, or System Admin can understand.

Agents should use the local release-notes-writer skill when drafting or reviewing entries.

Working Notes¶

For BetterFleet Manage:

• Public queue: bf-manage-web/docs/release-notes/working/next.public.md
• Internal queue: bf-manage-web/docs/release-notes/working/next.internal.md
• Holdback queue: bf-manage-web/docs/release-notes/working/holdback.md
• Published notes: bf-manage-web/docs/release-notes/releases/

For BetterFleet Plan, use the equivalent paths under betterfleet-bnl-ui/docs/release-notes/.

Use these change-type sections only when they contain real entries, in this order:

Added, Changed, Fixed, Removed, Deprecated, Security, Documentation

Do not keep empty headings or placeholder bullets. A working note with no queued entries should contain only front matter.

Writing Good Entries¶

A good release-note entry:

• names the changed behaviour or surface
• explains the practical outcome for a user, operator, customer, or System Admin
• gives enough detail for under-the-hood changes that customers can trust the software will not behave unexpectedly
• avoids ticket numbers, branch names, raw feature-flag names, and implementation detail unless the audience needs them
• links to relevant help docs using app-route paths such as help/settings/... when the entry points readers to a workflow or setting

Examples:

• User access changes now refresh more reliably after signing out and back in, so recently updated workspace roles are reflected without requiring a hard browser refresh.
• Customer admins can now access Settings > Power > Devices and Configuration Summary to set up and review on-site power integration devices for their depot. In a product release note, link the help page using the app route help/settings/depot-based-settings/power/.
• Audit log coverage now includes circuit configuration changes, including updates to circuit settings, power limit profiles, and time-of-use limits, so customers can request a clearer history of these changes for review.

Counterexamples:

• Feature flagged: manage-system-admin-users
• Improved permissions.
• No public changes queued yet.

Decision Flow¶

flowchart TD
    A["Change is ready to describe"] --> B{"Will a user, operator, or System Admin notice or rely on it?"}
    B -- "No" --> C["No release-note entry"]
    B -- "Yes" --> D{"Safe to publish now?"}
    D -- "No" --> E["Add to holdback.md"]
    D -- "Yes" --> F{"Audience"}
    F -- "Customers and normal users" --> G["Add to next.public.md"]
    F -- "System Admin or internal operators" --> H["Add to next.internal.md"]
    E --> I["Move later when publishable"]
    G --> J["Weekly promotion"]
    H --> J
    I --> D

Rules¶

• Prefer next.public.md whenever shipped scope can be communicated normally.
• Use next.internal.md only for internal or System Admin communication.
• Use holdback.md for real changes that are not ready to publish.
• Do not expose raw feature-flag names in public or internal release-note entries.
• Keep raw rollout labels in holdback.md when needed to prevent accidental publication.
• Treat Fully Released feature-flag work as normal shipped behaviour and start bounded flag cleanup.
• Update in-app help separately when the change affects what users see, expect, or need to do.

Promotion¶

When the weekly release is cut:

1. Review next.public.md, next.internal.md, and holdback.md.
2. Move any now-publishable holdback entries into the right publishable queue.
3. Publish next.public.md to releases/<version>.md only when it has content.
4. Publish next.internal.md to releases/<version>.internal.md only when it has content.
5. Reset promoted working notes to frontmatter-only templates.