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 @sumitshinde-84 @dimitrieh

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

@@ -0,0 +1,208 @@
+---
+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 written for 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 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 that are not yet generally available.
+
+If you are unsure, ask: "Would a user who opens FlowFuse tomorrow notice or benefit from this?" If the answer is no, it can likely be skipped. When in doubt, make it a quick discussion with the team, involving both engineering and product.
+
+## 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 being announced.
+
+## 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 the feature shipped, in `YYYY-MM-DD` format. |
+| `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 being announced. |
+
+## 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
+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 setup or action is required. 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 three 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.
+
+### 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 is shown in context, not just repeat the alt text.
+
+Screenshots should ideally be **1408px wide**. Height can vary depending on what is being shown.
+
+### Feature catalog and availability
+
+Changelog posts should ideally be tied 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, tier availability badges are injected into the changelog post automatically at build time. No additional markup needed 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. Any additions or availability changes in `featureCatalog.yaml` must be reviewed by product 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.
+
+| 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. They are written for engineers. Rewrite them from the user's perspective.
+
+## 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 a feature is best explained through concrete examples of 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. Changelog posts should be reviewed by a technical writer before merging. If no technical writer is available, product can review as a backup.