handbook: add guide for writing changelog posts#4674
handbook: add guide for writing changelog posts#4674sumitshinde-84 wants to merge 18 commits intomainfrom
Conversation
✅ Deploy Preview for flowforge-website ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
✅ Deploy Preview for flowforge-website ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Before merging this PR, please merge #4675 as this change depends on it. |
dimitrieh
left a comment
dimitrieh
left a comment
There was a problem hiding this comment.
@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
|
|
||
| ## 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. |
There was a problem hiding this comment.
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
|
Before we merge this, I think it's worth taking a step back to align on a couple of things first:
Once we're clear on those, we'll be in a much better position to decide who should own changelog entries, and whether that should vary by entry type. I'm also conscious of the frequency here. Looking at what we actually ship, this isn't a once-a-month activity, it's multiple entries some weeks. If we're asking engineers to write these on top of everything else, we need to be honest about whether that's sustainable, or whether we're quietly adding to the burden every sprint without acknowledging it. No one wants a process that makes engineers feel like they're writing marketing copy on top of shipping features. Let's make sure we understand the strategy first (who it's for, what we want it to do) and then the guidelines will follow naturally from that rather than the other way around. @sumitshinde-84, none of this is a criticism of the work here, this is clearly well thought out. Just want to make sure we're building the right thing before we lock it in. |
|
@allthedoll I agree with you. My understanding there was that we are writing these anyway and they are already established process, now making them more visible/useful and aligned for potential marketing purposes. I will put this up in the next engineering meeting for discussion so we can have the context and align on intent Cc: @sumitshinde-84 |
|
Thanks @allthedoll , really valid points ! Could you all discuss this in the next eng meeting and share the outcome here? Happy to update the PR once there's alignment on the strategy. |
|
@sumitshinde-84 there is an action point on Jamie and my plate now regarding this after the Eng meeting today. After that we'll know more :). We now got required context from the eng meeting. |
|
@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 trigger
Noting when to make a changelog
Noting Cloud vs Self-hosted
Reviewers
Suggestion: include a Claude prompt
Example:
Next steps
|
| ## 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. | ||
|
|
There was a problem hiding this comment.
| 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. |
|
|
||
| ## 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. |
There was a problem hiding this comment.
| 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. | |
| 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 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. | ||
|
|
There was a problem hiding this comment.
| ## How changelog posts are triggered | |
| Changelog posts should be identified 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 changelog work is planned alongside delivery, rather than being remembered (or missed) at release time. |
| 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. |
There was a problem hiding this comment.
| 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. | |
| 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_). |
| /package-lock.json @FlowFuse/engineering @Yndira-E | ||
|
|
||
| # Changelog posts (tech writer required, product as backup) | ||
| /handbook/engineering/releases/writing-changelog @sumitshinde-84 @dimitrieh |
There was a problem hiding this comment.
| /handbook/engineering/releases/writing-changelog @sumitshinde-84 @dimitrieh | |
| /handbook/engineering/releases/writing-changelog @FlowFuse/marketing @FlowFuse/product @FlowFuse/engineering @sumitshinde-84 @dimitrieh |
I don't know how the handbook works and I'm guessing a team assigned will break it??
|
|
||
| ## 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. |
There was a problem hiding this comment.
| 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. | |
| Follow the standard [Git workflow](/handbook/company/guides/git/) to raise a PR against the website repository. | |
| Changelog posts should be reviewed by at least one of: | |
| - Product | |
| - Marketing | |
| - Engineering | |
| Aim for 1–2 reviewers to ensure accuracy and clarity. This avoids bottlenecks if specific individuals are unavailable. |
| 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. | ||
|
|
There was a problem hiding this comment.
| ## 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 user action is required | |
| > - 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. |
4 participants
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