handbook: add guide for writing changelog posts

CODEOWNERS

@@ -19,6 +19,8 @@
 # Change in values need sign off from both the CEO and CTO
 /src/handbook/company/values.md @knolleary @ZJvandeWeg
 
-
 # Package-lock.json (engineering team)
 /package-lock.json @FlowFuse/engineering  @Yndira-E
+
+# Changelog posts (tech writer required, product as backup)
+/handbook/engineering/releases/writing-changelog @FlowFuse/marketing  @FlowFuse/product @FlowFuse/engineering

src/handbook/engineering/releases/writing-changelog.md

@@ -0,0 +1,248 @@
+---
+navTitle: Changelog Posts
+---
+
+# Writing Changelog Posts
+
+The [FlowFuse Changelog](/changelog/) is where users go to see what has shipped. It is a place to communicate product updates clearly and directly to FlowFuse users.
+
+A changelog post is not a PR description or a release note. It is a short, focused announcement aimed at FlowFuse users who want to quickly understand what changed and how it impacts them.
+
+## When to write one
+
+Write a changelog post when you ship something a user would notice or benefit from. This means the change is **live in production on FlowFuse Cloud** and visible to users.
+
+This includes new features, meaningful improvements to existing functionality, behaviour changes users need to be aware of, and breaking changes that require user action.
+
+Do not write changelog posts for internal tooling changes with no user-visible impact, routine dependency bumps, minor bug fixes the average user would never encounter, or changes behind a feature flag you have not yet released to everyone.
+
+If you are unsure, ask: "Would a user who opens FlowFuse tomorrow notice or benefit from this?" If the answer is no, you can likely skip it. When in doubt, make it a quick discussion with the team, involving both engineering and product.
+
+## Identifying what needs a changelog post
+
+Product and engineering identify changelog posts during refinement, not after work is complete.
+
+- Product creates a `changelog` ticket for any work that requires a changelog post
+- Engineering and Product are jointly responsible for asking: "Does this need a changelog?" during refinement
+
+This ensures the team plans changelog work alongside delivery, rather than remembering (or missing) them at release time.
+
+## Creating the file
+
+Posts live in the [website repository](https://github.com/FlowFuse/website/tree/main/src/changelog). Navigate to the correct year and month folder for when the feature shipped, and create a new `.md` file. If the folder for that month does not exist yet, create it.
+
+```
+src/changelog/YYYY/MM/your-post-slug.md
+```
+
+The slug should be short, lowercase, and hyphen-separated, describing the feature you are announcing.
+
+## Frontmatter
+
+Every post requires the following fields at the top of the file:
+
+| Field | Notes |
+|---|---|
+| `title` | The name of the feature or change. Title case. Keep it short. |
+| `description` | One sentence summarising the change. This appears in link previews and search results, so it should make sense without any surrounding context. |
+| `date` | The date and time the feature shipped, in `YYYY-MM-DD HH:mm:ss` format (e.g., `2026-03-24 17:00:00`). The timestamp ensures correct sorting when you add multiple features on the same day. |
+| `authors` | Your handle from `src/_data/team`. Leave it out if there is no single clear author. |
+| `tags` | Always include `changelog`. |
+| `issues` | A list of related GitHub issue URLs. Link any issues that tracked the work this post announces. |
+
+## Starting Template
+
+You can start a new changelog post with the following template:
+
+```markdown
+---
+title: Short Feature Title
+description: One sentence summarising the change, written for a user, not an engineer.
+date: YYYY-MM-DD HH:mm:ss
+authors: your-handle
+tags:
+  - changelog
+issues:
+  - https://github.com/FlowFuse/<repo>/issues/<id>
+---
+
+<!-- 
+  WHAT CHANGED — Lead with it. One or two sentences max.
+  Bad:  "Refactored snapshot restore logic for dev mode instances."
+  Good: "You can now restore snapshots without leaving developer mode."
+
+  If this is a BREAKING CHANGE, say so here in bold before anything else:
+  **FlowFuse vX.Y requires [thing]. You will need to [action] before upgrading.**
+-->
+
+[What changed, stated plainly.]
+
+<!-- WHY IT MATTERS — The "so what". Don't skip this. -->
+
+[The problem this solves or the benefit it brings.]
+
+<!-- HOW TO GET STARTED — Only include this if the user needs to take action. Delete if it just works. -->
+
+To get started:
+
+1. [First step]
+2. [Second step]
+
+<!-- SCREENSHOT — Include for any visual change. Delete if not applicable. -->
+
+![Alt text describing the UI shown](./images/your-image.png)
+*Caption describing what is shown in context.*
+
+<!-- AVAILABILITY — Include if this is plan- or version-gated. Delete if available to everyone. -->
+
+This feature is available to [plan/tier] users of FlowFuse Cloud and [licence type] Self Hosted users from [vX.Y].
+```
+
+## Writing the post
+
+There is no fixed template - the right length and shape depends on the change. A small improvement might be two sentences and a screenshot. A complex feature might need steps, multiple screenshots, and an availability note. Use your judgement.
+
+That said, every post should answer four questions:
+
+**What changed?** State it plainly in the opening. Do not make the user read three paragraphs before they find out what the post is about.
+
+**Why does it matter?** Explain the benefit or the problem it solves. This is the difference between a changelog post and a bare release note. Without it, users have no reason to care.
+
+**What do they need to do?** If the feature requires setup or user action, explain how to get started. If it just works, you do not need this.
+
+**Where is it available?** The change is live on FlowFuse Cloud. Self Hosted users will receive it in the next release (_vX.Y_).
+
+### Screenshots
+
+Include a screenshot for any visual change. Reference images from `src/img/` like this:
+
+```markdown
+![Alt text](./images/image.png)
+*Caption describing what is shown*
+```
+
+Always add a caption in italics directly below the image. The caption should describe what the image shows in context, not just repeat the alt text.
+
+Screenshots should ideally be **1408px wide**. Height can vary depending on what you are showing.
+
+### Feature catalog and availability
+
+Ideally, tie each changelog post to a feature defined in [`featureCatalog.yaml`](https://github.com/FlowFuse/website/blob/main/src/_data/featureCatalog.yaml). The catalog is the single source of truth for tier availability across FlowFuse.
+
+When you ship a changelog post for a catalogued feature, update the feature's entry in `featureCatalog.yaml` to include the changelog `url` and `release` number:
+
+```yaml
+changelog:
+  - url: /changelog/2026/03/your-post-slug/
+    release: "2.29"
+```
+
+Once that entry is in place, the build injects tier availability badges into the changelog post automatically. You need no additional markup in the post itself.
+
+If the feature does not yet exist in the catalog, add it or flag it for someone to add before the post goes live. If the feature's tier availability has changed alongside this release, update the relevant fields in the catalog too. Product must review any additions or availability changes in `featureCatalog.yaml` before merging.
+
+Always write an availability note in the post as well. Tier badges communicate the tier, but prose tells the user what it means for them. Write it like this:
+
+> This feature is available to Enterprise tier users of FlowFuse Cloud and Enterprise Licensed Self Hosted users from vX.Y.
+
+Put it at the end of the post, or immediately after the main announcement if it affects whether the user can access the feature at all.
+
+## Writing style
+
+Write for the user, not the engineer. Every changelog entry can tell two stories - what changed in the code, and what improved for the user. Always tell the second one.
+
+Write in _active voice_. Active voice puts the subject before the verb. The user is doing something, or something is now possible for them. When possible, write with “you” as the subject. It makes writing more direct, clear, and engaging. It also makes for better storytelling.
+| Instead of this | Write this |
+|---|---|
+| Updated authentication API response handling | Logging in is noticeably faster |
+| Refactored snapshot restore logic for dev mode instances | You can now restore snapshots without leaving developer mode |
+| Restart sequencing updated for HA instances | HA instances now restart one at a time, so there is no downtime during updates |
+
+Be specific. Vague entries are useless. Compare:
+
+**Weak:** Minor improvements to the Expert
+
+**Strong:** The Expert now has Palette Awareness - ask it about your installed nodes, available updates, or which packages are disabled, without leaving the chat interface.
+
+Keep it short. A changelog post is not a blog post. If the feature needs more depth, link to documentation rather than expanding the post.
+
+Avoid jargon unless it is standard FlowFuse or Node-RED vocabulary. If a technical term is unavoidable, give enough context that a non-expert can follow.
+
+Do not paste PR titles or commit messages, as those are for our internal engineering team. Rewrite them from the user's perspective.
+
+## Drafting with AI
+
+If you prefer, you can use an LLM to draft a first version of your changelog post.
+
+Paste the following prompt into your tool of choice along with your PR description, commit messages, or technical notes:
+
+> You are writing a FlowFuse changelog post. The audience is FlowFuse users — cloud customers and self-hosted admins. Using the content I paste below, write a changelog post that:
+> - Opens with what changed, stated plainly in active voice
+> - Focuses on what the user can now do (use “you” where possible)
+> - Explains the user benefit in one or two sentences
+> - Includes a 'getting started' section only if the user needs to take action
+> - Ends with: "This change is live on FlowFuse Cloud. Self Hosted users will receive it in the next release (vX.Y)."
+>
+> Do not use PR titles or commit message language. Write for someone who just opened FlowFuse and wants to know what’s new.
+>
+> Here is the technical context:
+> [paste here]
+
+Always review and edit the output before publishing.
+## Examples
+
+### A small but useful improvement
+
+> As of today, you can now duplicate a hosted instance into a different application within your team.
+>
+> It is a small (but important) improvement that just makes things that little bit easier.
+
+*Source: [Duplicate Instances Across Different Applications](https://flowfuse.com/changelog/2025/10/duplicate-instances-across-applications/)*
+
+Short, honest about the size of the change, and gets straight to the point.
+
+### Showing what is now possible
+
+> You can now ask the Expert about your installed nodes, versions, and available updates without leaving the chat interface. For example:
+>
+> - Do I have any nodes installed that can send emails?
+> - Are my palette nodes up to date?
+> - Are any nodes on my palette disabled?
+> - Can you suggest a node package that would replace this complex function code?
+
+*Source: [FlowFuse Expert: Palette Queries](https://flowfuse.com/changelog/2026/01/ff-expert-palette-queries/)*
+
+Instead of describing the feature abstractly, this shows exactly how a user will interact with it. Use this approach whenever concrete examples best explain a feature — what the user can now say or do.
+
+### Translating a technical change into a user benefit
+
+> Any action that triggers a restart of the Node-RED instance will now restart them in sequence rather than in parallel. This means there should be no downtime for this instance.
+>
+> This feature is available to Enterprise Licensed Self Hosted users and Enterprise tier users of FlowFuse Cloud.
+
+*Source: [HA Hosted Instance Rolling Restart](https://flowfuse.com/changelog/2026/02/ha-instance-rolling-restart/)*
+
+The technical detail is there, but the sentence that follows immediately translates it into what the user actually cares about. Always pair the *what* with the *so what*.
+
+### A breaking change
+
+> **FlowFuse v2.24.0 requires Node.js v20 or higher.** If you are running an older version, you will need to upgrade Node.js before updating FlowFuse.
+>
+> Node.js v18 reached end of life in April 2025 and no longer receives security updates. This change ensures FlowFuse continues to run on a supported and secure runtime.
+>
+> To check your current version, run `node --version`.
+
+*Source: [Node.js v20 Minimum Version Requirement](https://flowfuse.com/changelog/2025/11/minimum-nodejs-version/)*
+
+State what is changing and who it affects in the first sentence. Then explain why. Then tell the user exactly what to do. A user who needs to act should have everything they need without leaving the page.
+
+## Raising a PR
+
+Follow the standard [Git workflow](/handbook/company/guides/git/) to raise a PR against the website repository.
+
+Have at least one of the following review the post before it goes live:
+- Product
+- Marketing
+- Engineering
+
+Aim for 1–2 reviewers to ensure accuracy and clarity. This avoids bottlenecks if specific individuals are unavailable.