Release Notes

This guide defines the BetterFleet release-note operating model.

Purpose

Release notes are human-readable summaries of shipped product impact.

Use GitLab Feature Flags with this guide for BetterFleet Manage feature-flagged rollout.

• Use them to explain what changed in the system in terms a user, operator, or System Admin can understand.
• Prefer the outcome or behaviour change over the implementation detail.
• Technical or backend work still belongs in release notes when it changes what people can do, notice, rely on, or experience, including performance, reliability, permissions, workflows, and important edge-case handling.
• Purely internal refactors, test-only changes, or tooling tidy-ups do not belong unless they lead to a meaningful user- or operator-visible impact.
• When writing an entry, ask: if this shipped, what would a real person care about?

What To Capture

• New capabilities or newly available actions.
• Changed behaviour, workflow, visibility, permissions, or defaults.
• Fixes to bugs, edge cases, or failure modes that matter to real usage.
• Performance, reliability, or operational improvements when people would reasonably notice the difference or benefit from it.
• Internal or System Admin operational changes in next.internal.md when they matter to those audiences.

Default Shipping Posture

• Aim to ship small, user-relevant increments continuously rather than batching large piles of hidden work.
• Prefer next.public.md as the normal destination for shipped scope.
• Use next.internal.md only when the change is genuinely for internal or System Admin audiences.
• Use holdback.md sparingly and temporarily for scope that is not yet safe to publish.
• If holdback.md starts to accumulate, treat that as a signal to reshape the work into smaller releasable slices, clarify rollout gates, or move now-safe entries into next.public.md or next.internal.md.
• A healthy steady state is a regular flow of meaningful entries through next.public.md, with only limited temporary content in next.internal.md and holdback.md.

Product Repo Artifacts

For BetterFleet Manage, release-note content lives in:

• bf-manage-web/docs/release-notes/working/next.public.md
• bf-manage-web/docs/release-notes/working/next.internal.md
• bf-manage-web/docs/release-notes/working/holdback.md
• bf-manage-web/docs/release-notes/releases/<version>.md
• bf-manage-web/docs/release-notes/releases/<version>.internal.md
• bf-manage-web/docs/release-notes/nav.json

Use the same product-repo-relative structure in other BetterFleet UI repos if they adopt release notes later.

Working Release Notes

• Treat docs/release-notes/working/ as the editable release queue rather than published history.
• next.public.md is the working note for content that is safe to publish in the next public release note.
• next.internal.md is the working note for content that is safe to publish in the next internal or System Admin release note.
• holdback.md is the working note for content that is not yet ready to publish in either audience.
• Keep next.public.md and next.internal.md parallel when the same release needs both audiences.
• Keep holdback.md separate so promotion cannot accidentally publish entries that are still withheld.
• Within each working note, use changelog-style subsections in this order:
  • Added
  • Changed
  • Fixed
• Add Removed, Deprecated, Security, or a distinct Beta section only when they are needed.
• Public and internal queued entries sit directly inside their change-type subsection.
• Holdback entries may be grouped by feature flag, rollout label, or approval gate inside their change-type subsection.
• Manage Internal work, shown in sysadmin as Pre-Release, should usually stay in holdback.md unless it is intentionally ready for internal or System Admin communication now.
• Manage Beta work may belong in next.public.md, next.internal.md, or holdback.md depending on who should be told about it now.
• Manage Fully Released work should be treated as normal shipped behavior in release communication and should start bounded feature-flag cleanup rather than remain indefinitely behind All Users.
• Empty subsections may use a single placeholder bullet such as No public fixes queued yet.
• Every relevant story that changes releasable behaviour should add or revise the correct working release note as part of delivery.
• Every relevant MR should explicitly check whether release-note content needs to be updated.
• Write entries for people, not for Git history: say what changed and why it matters, not which files, frameworks, or internal implementation details were touched.
• Treat holdback.md as a short-lived exception queue, not as the normal resting place for delivered work.

Purpose summary:

• next.public.md: ready for the next public note.
• next.internal.md: ready for the next internal note.
• holdback.md: intentionally not publishable yet.

Example working-note structure:

<!-- working/next.public.md -->

---
title: "Next public release note"
slug: "next.public"
---

## Added

- New generally available capability.

## Changed

- Existing user-facing workflow updated.

## Fixed

- Customer-visible defect resolved.

<!-- working/next.internal.md -->

---
title: "Next internal release note"
slug: "next.internal"
---

## Added

- Internal-only operational or System Admin improvement.

## Changed

- Shipped internal workflow updated.

<!-- working/holdback.md -->

---
title: "Holdback release notes"
slug: "holdback"
---

## Added

### Feature flag: `new-rollout`

- Feature-flagged note that must not be promoted yet.

Published Note Rules

• Published release notes live under docs/release-notes/releases/.
• Create one public versioned markdown file per published release.
• Add a same-version .internal.md companion when the release has internal or System Admin content worth surfacing in-app.
• Do not create published files from working/holdback.md.
• Keep any Beta content inside the public versioned file if it is relevant to that release.

Weekly Promotion Flow

When the weekly release is cut:

1. Review working/next.public.md, working/next.internal.md, and working/holdback.md.
2. Move any now-publishable entries out of working/holdback.md and into working/next.public.md or working/next.internal.md before promotion.
3. Copy the public queued entries into releases/<version>.md.
4. Copy the internal queued entries into releases/<version>.internal.md when there is internal content to publish.
5. Remove or revise the promoted entries in working/next.public.md and working/next.internal.md so they reflect only still-unpublished queued scope.
6. Commit the new versioned file or files under bf-manage-web/docs/release-notes/releases/; the in-app release-notes UI will list the public note under Published releases.

In-App Surface Rules

• The in-app release-notes UI should expose published public release notes from docs/release-notes/releases/.
• System Admin users should also see the internal companion content for the same release when a .internal.md file exists.
• Normal users should not see internal headings or internal content.
• PDF export should explicitly offer the scopes the current user can access:
  • Public for all users
  • Internal for System Admin users when an internal companion exists
  • Public + Internal for System Admin users when an internal companion exists
• working/next.public.md is a working artifact and should not be part of the published release-note navigation.
• working/next.internal.md and working/holdback.md are also working artifacts and should not be part of the published release-note navigation.