handbook: add guide for writing changelog posts

[sumitshinde-84]

Description

Adds a handbook guide explaining how to write changelog posts for flowfuse.com/changelog/.

Covers when to write one, how to structure the file and frontmatter, writing style guidance, and real examples from the existing changelog as discussed with @dimitrieh

Related Issue(s)

Checklist

• I have read the contribution guidelines
• I have considered the performance impact of these changes
• Suitable unit/system level tests have been added and they pass
• Documentation has been updated
• For blog PRs, an Art Request has been created (instructions)

[netlify]

✅ Deploy Preview for flowforge-website ready!

Name	Link
🔨 Latest commit	22ec3f9
🔍 Latest deploy log	https://app.netlify.com/projects/flowforge-website/deploys/69b10752d3c2190008551462
😎 Deploy Preview	https://deploy-preview-4674--flowforge-website.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 89 (🔴 down 2 from production) Accessibility: 81 (no change from production) Best Practices: 100 (no change from production) SEO: 91 (no change from production) PWA: - View the detailed breakdown and full score reports

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[netlify]

✅ Deploy Preview for flowforge-website ready!

Name	Link
🔨 Latest commit	afa54e1
🔍 Latest deploy log	https://app.netlify.com/projects/flowforge-website/deploys/69ca5799f175370008940190
😎 Deploy Preview	https://deploy-preview-4674--flowforge-website.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 85 (🔴 down 1 from production) Accessibility: 81 (no change from production) Best Practices: 100 (no change from production) SEO: 91 (no change from production) PWA: - View the detailed breakdown and full score reports

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[sumitshinde-84]

Before merging this PR, please merge #4675 as this change depends on it.

[dimitrieh]

@sumitshinde-84 thanks for writing this up!

Left a couple of suggestions and requested changes.

Calling in help to review this from @Steve-Mcl @cstns if possible, @n-lark as well for a fresh perspective on this ✨

cc: @allthedoll

[dimitrieh]

I am sure engineering has an opinion on this has well. :)

@Steve-Mcl can you have a look here?

---

A quick search gives:

There's no handbook page that defines criteria like "write a changelog entry when X" — it seems the public-facing changelog entries at flowfuse.com/changelog are produced more by editorial judgment (product/marketing) than a written rule. That might actually be a gap worth filling, especially given the work you've been doing with Sumit and the release templates you're setting up

We have some existing documentation at https://flowfuse.com/handbook/engineering/project-management/#changelog-%26-release-communication

[dimitrieh]

@allthedoll can you have a look here?

[allthedoll]

@dimitrieh verify we've addressed this but I think we're good.

[sumitshinde-84]

@

@sumitshinde-84 so we did talk about this in the engineering meeting today (cc @dimitrieh); here are my comments now that we've had that discussion!

Style Guidance

• The style guidance and examples section are genuinely strong, and having real changelog links as models is ✨

• ‼️ TODO: One addition to the writing style section: write in active voice. This is worth stating explicitly alongside the other style rules.

  • Compare: "Snapshot restore logic has been updated" vs. "You can now restore snapshots without leaving developer mode."
  • Active voice and user-framing tend to arrive together, but calling it out removes ambiguity.
  • For those just entering the chat, active voice is a sentence structure where the subject performs the action expressed by the verb; the subject comes before the verb. This makes for more direct, clear, engaging writing and better story telling.

The trigger

• The current framing ("write when you ship something a user would notice") is 📈

  • But , more specifically, this is once a "ship" is verified in production (on Cloud) ✅
  • ‼️ TODO: Let's update this to reflect that.

Noting when to make a changelog

• ‼️ TODO: Update process for how we know when to write a changelog:

  • @FlowFuse/product will open a changelog ticket during refinement for any items requiring a changelog update

    • @FlowFuse/engineering and @FlowFuse/product are jointly responsible for remembering to ask this during refinements

Noting Cloud vs Self-hosted

• What's live on Cloud now vs. what self-hosted customers get in the next release is actually the core purpose of the changelog. Worth making that explicit here.
• ‼️ TODO: Let's add that the changelog should call this out (see Claude example below for inspo).

Reviewers

• I'm worried this is too narrow. What if one or both of you is out?
• ‼️ TODO: Let's assign @FlowFuse/marketing @FlowFuse/product and @FlowFuse/engineering and take 1-2 reviews. 💪🏼

Side note here: It's on my long-term tech debt to convert all CODEOWNERS files to teams from individuals. Best practices and all that.

Suggestion: include a Claude prompt

• Given that we want engineers to write these without it feeling like a lift, consider adding a ready-to-use AI prompt to the doc

  • This removes a meaningful barrier to consistency, especially for engineers who are capable but don't want to context-switch into marketing-adjacent writing or for whom English is not their first language.

• ‼️ TODO: Add an AI prompt for drafting changelogs 🤖

Example:

Drafting with AI
Paste the following prompt into LLM 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 — not engineers. Using the content I paste below, write a changelog post that: (1) opens with what changed, stated plainly in active voice; (2) explains the user benefit in one or two sentences; (3) includes a 'getting started' section only if user action is required; (4) ends with an availability note in this format: 'This feature is available to [tier] users of FlowFuse Cloud and [licence type] Self Hosted users from 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]"

Next steps

• I will attempt to put these into code suggestions now 👼🏼

Thanks @allthedoll, I have applied all the suggestions except one—adding the dept as a code owner. Could you please review this?

[allthedoll]

LGTM! 🚀 🙌

[dimitrieh]

FYI: Just briefly discussed with @allthedoll. She will do another pass

[allthedoll]

@dimitrieh @sumitshinde-84 @Yndira-E one final pass please?

[sumitshinde-84]

LGTM !

[dimitrieh]

@sumitshinde-84 can you review #4785 which merges into this one. After that we can merge imo

[dimitrieh]

Merging this regardless. #4785 can be merged separately into main.