From 22ec3f9b686a849b86f3904b4de35c7325c69de0 Mon Sep 17 00:00:00 2001 From: sumitshinde-84 Date: Wed, 11 Mar 2026 11:39:17 +0530 Subject: [PATCH 01/23] handbook: add guide for writing changelog posts --- .../engineering/releases/writing-changelog.md | 140 ++++++++++++++++++ 1 file changed, 140 insertions(+) create mode 100644 src/handbook/engineering/releases/writing-changelog.md diff --git a/src/handbook/engineering/releases/writing-changelog.md b/src/handbook/engineering/releases/writing-changelog.md new file mode 100644 index 0000000000..cd09cbdb02 --- /dev/null +++ b/src/handbook/engineering/releases/writing-changelog.md @@ -0,0 +1,140 @@ +--- +navTitle: Changelog Posts +--- + +# Writing Changelog Posts + +The [FlowFuse Changelog](https://flowfuse.com/changelog/) is where users find out what has shipped. It is one of the most read pages on the site and one of the most direct ways we communicate value to our users. + +A changelog post is not a PR description or a release note. It is a short, focused announcement written for a FlowFuse user - someone who is busy and wants to know quickly what changed and whether it matters to 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 not, skip it. + +## 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. It should describe the feature, not the release - `duplicate-instances-across-applications`, not `v2-25-0`. + +## 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. | + +## 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](https://flowfuse.com/img/your-image.webp) +*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. + +### Availability + +If a feature is only available on certain plans or from a specific version, say so. Put this at the end of the post, or immediately after the main announcement if it affects whether the user can access it at all. + +### Breaking changes + +If a change could break an existing user setup or requires action before upgrading, say so in the first paragraph. Do not bury it. + +## 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 + +> We're leveling up! FlowFuse now requires **Node.js v20 or higher** to run. +> +> This change is effective from v2.24.0 onwards. + +*Source: [Node.js v20 Minimum Version Requirement](https://flowfuse.com/changelog/2025/11/minimum-nodejs-version/)* + +The requirement is in the first sentence, bolded, impossible to miss. Users who need to act see it immediately. + +## 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 at least one other team member before merging. \ No newline at end of file From 723a7887bdc558ad647211f54f00ee5e47b8999c Mon Sep 17 00:00:00 2001 From: "sumit shinde ( Roni )" <110285294+sumitshinde-84@users.noreply.github.com> Date: Wed, 11 Mar 2026 11:42:44 +0530 Subject: [PATCH 02/23] Update writing-changelog.md --- .../engineering/releases/writing-changelog.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/handbook/engineering/releases/writing-changelog.md b/src/handbook/engineering/releases/writing-changelog.md index cd09cbdb02..b668b88551 100644 --- a/src/handbook/engineering/releases/writing-changelog.md +++ b/src/handbook/engineering/releases/writing-changelog.md @@ -54,7 +54,7 @@ That said, every post should answer three questions: Include a screenshot for any visual change. Reference images from `src/img/` like this: ```markdown -![Alt text](https://flowfuse.com/img/your-image.webp) +![Alt text](./images/your-image.png) *Caption describing what is shown* ``` @@ -98,7 +98,7 @@ Do not paste PR titles or commit messages. They are written for engineers. Rewri > > 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/)* +*Source: [Duplicate Instances Across Different Applications](/changelog/2025/10/duplicate-instances-across-applications/)* Short, honest about the size of the change, and gets straight to the point. @@ -111,7 +111,7 @@ Short, honest about the size of the change, and gets straight to the point. > - 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/)* +*Source: [FlowFuse Expert: Palette Queries](/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. @@ -121,7 +121,7 @@ Instead of describing the feature abstractly, this shows exactly how a user will > > 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/)* +*Source: [HA Hosted Instance Rolling Restart](/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*. @@ -131,10 +131,10 @@ The technical detail is there, but the sentence that follows immediately transla > > This change is effective from v2.24.0 onwards. -*Source: [Node.js v20 Minimum Version Requirement](https://flowfuse.com/changelog/2025/11/minimum-nodejs-version/)* +*Source: [Node.js v20 Minimum Version Requirement](/changelog/2025/11/minimum-nodejs-version/)* The requirement is in the first sentence, bolded, impossible to miss. Users who need to act see it immediately. ## 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 at least one other team member before merging. \ No newline at end of file +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 other team member before merging. From 99500f26a792fbc3854d8b9d93e5faf278cac0ba Mon Sep 17 00:00:00 2001 From: "sumit shinde ( Roni )" <110285294+sumitshinde-84@users.noreply.github.com> Date: Wed, 11 Mar 2026 12:04:06 +0530 Subject: [PATCH 03/23] Update writing-changelog.md --- .../engineering/releases/writing-changelog.md | 38 ++++++++++++------- 1 file changed, 24 insertions(+), 14 deletions(-) diff --git a/src/handbook/engineering/releases/writing-changelog.md b/src/handbook/engineering/releases/writing-changelog.md index b668b88551..aeed3bfdf2 100644 --- a/src/handbook/engineering/releases/writing-changelog.md +++ b/src/handbook/engineering/releases/writing-changelog.md @@ -1,12 +1,9 @@ ---- -navTitle: Changelog Posts ---- - # Writing Changelog Posts The [FlowFuse Changelog](https://flowfuse.com/changelog/) is where users find out what has shipped. It is one of the most read pages on the site and one of the most direct ways we communicate value to our users. -A changelog post is not a PR description or a release note. It is a short, focused announcement written for a FlowFuse user - someone who is busy and wants to know quickly what changed and whether it matters to them. +A changelog post is not a PR description or a release note. It is a short, focused announcement written for a FlowFuse user, someone who is busy and wants to know quickly what changed and whether it matters to them. + ## When to write one @@ -16,6 +13,7 @@ Do not write changelog posts for internal tooling changes with no user-visible i If you are unsure, ask: *would a user who opens FlowFuse tomorrow notice or benefit from this?* If not, skip it. + ## 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. @@ -24,7 +22,8 @@ Posts live in the [website repository](https://github.com/FlowFuse/website/tree/ src/changelog/YYYY/MM/your-post-slug.md ``` -The slug should be short, lowercase, and hyphen-separated. It should describe the feature, not the release - `duplicate-instances-across-applications`, not `v2-25-0`. +The slug should be short, lowercase, and hyphen-separated, describing the feature being announced. + ## Frontmatter @@ -36,6 +35,9 @@ Every post requires the following fields at the top of the file: | `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. | + ## Writing the post @@ -54,7 +56,7 @@ That said, every post should answer three questions: Include a screenshot for any visual change. Reference images from `src/img/` like this: ```markdown -![Alt text](./images/your-image.png) +![Alt text](https://flowfuse.com/img/your-image.webp) *Caption describing what is shown* ``` @@ -68,6 +70,7 @@ If a feature is only available on certain plans or from a specific version, say If a change could break an existing user setup or requires action before upgrading, say so in the first paragraph. Do not bury it. + ## 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. @@ -90,6 +93,7 @@ Avoid jargon unless it is standard FlowFuse or Node-RED vocabulary. If a technic 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 @@ -98,10 +102,11 @@ Do not paste PR titles or commit messages. They are written for engineers. Rewri > > It is a small (but important) improvement that just makes things that little bit easier. -*Source: [Duplicate Instances Across Different Applications](/changelog/2025/10/duplicate-instances-across-applications/)* +*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: @@ -111,29 +116,34 @@ Short, honest about the size of the change, and gets straight to the point. > - 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](/changelog/2026/01/ff-expert-palette-queries/)* +*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](/changelog/2026/02/ha-instance-rolling-restart/)* +*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 -> We're leveling up! FlowFuse now requires **Node.js v20 or higher** to run. +Here is how the Node.js v20 requirement should have been written: + +> **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 reaches 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. > -> This change is effective from v2.24.0 onwards. +> To check your current version, run `node --version`. -*Source: [Node.js v20 Minimum Version Requirement](/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. -The requirement is in the first sentence, bolded, impossible to miss. Users who need to act see it immediately. ## Raising a PR From a2aca5144f888076db41c565b5d148acaa9cf928 Mon Sep 17 00:00:00 2001 From: "sumit shinde ( Roni )" <110285294+sumitshinde-84@users.noreply.github.com> Date: Wed, 11 Mar 2026 12:06:34 +0530 Subject: [PATCH 04/23] Update writing-changelog.md --- src/handbook/engineering/releases/writing-changelog.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/src/handbook/engineering/releases/writing-changelog.md b/src/handbook/engineering/releases/writing-changelog.md index aeed3bfdf2..afa4015857 100644 --- a/src/handbook/engineering/releases/writing-changelog.md +++ b/src/handbook/engineering/releases/writing-changelog.md @@ -1,3 +1,7 @@ +--- +navTitle: Changelog Posts +--- + # Writing Changelog Posts The [FlowFuse Changelog](https://flowfuse.com/changelog/) is where users find out what has shipped. It is one of the most read pages on the site and one of the most direct ways we communicate value to our users. @@ -134,14 +138,14 @@ The technical detail is there, but the sentence that follows immediately transla ### A breaking change -Here is how the Node.js v20 requirement should have been written: - > **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 reaches 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. +> 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. From a54d3f566e1edd05cfc6a274dba8b25c0893f2fd Mon Sep 17 00:00:00 2001 From: "sumit shinde ( Roni )" <110285294+sumitshinde-84@users.noreply.github.com> Date: Wed, 11 Mar 2026 12:14:42 +0530 Subject: [PATCH 05/23] Update writing-changelog.md --- src/handbook/engineering/releases/writing-changelog.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/handbook/engineering/releases/writing-changelog.md b/src/handbook/engineering/releases/writing-changelog.md index afa4015857..677db20bca 100644 --- a/src/handbook/engineering/releases/writing-changelog.md +++ b/src/handbook/engineering/releases/writing-changelog.md @@ -60,7 +60,7 @@ That said, every post should answer three questions: Include a screenshot for any visual change. Reference images from `src/img/` like this: ```markdown -![Alt text](https://flowfuse.com/img/your-image.webp) +![Alt text](./images/image.png) *Caption describing what is shown* ``` From a95abf828ccf29f1c6dff3d2965deee6a319e49c Mon Sep 17 00:00:00 2001 From: "sumit shinde ( Roni )" <110285294+sumitshinde-84@users.noreply.github.com> Date: Mon, 16 Mar 2026 20:49:43 +0530 Subject: [PATCH 06/23] Update writing-changelog.md --- src/handbook/engineering/releases/writing-changelog.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/src/handbook/engineering/releases/writing-changelog.md b/src/handbook/engineering/releases/writing-changelog.md index 677db20bca..17c27289ac 100644 --- a/src/handbook/engineering/releases/writing-changelog.md +++ b/src/handbook/engineering/releases/writing-changelog.md @@ -4,10 +4,9 @@ navTitle: Changelog Posts # Writing Changelog Posts -The [FlowFuse Changelog](https://flowfuse.com/changelog/) is where users find out what has shipped. It is one of the most read pages on the site and one of the most direct ways we communicate value to our users. - -A changelog post is not a PR description or a release note. It is a short, focused announcement written for a FlowFuse user, someone who is busy and wants to know quickly what changed and whether it matters to them. +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 a FlowFuse user, someone who is busy and wants to quickly understand what changed and whether it affects them. ## When to write one From bf1884921c04219f8de37903868782b26b9aa44f Mon Sep 17 00:00:00 2001 From: "sumit shinde ( Roni )" <110285294+sumitshinde-84@users.noreply.github.com> Date: Mon, 16 Mar 2026 21:34:18 +0530 Subject: [PATCH 07/23] Update writing-changelog.md --- .../engineering/releases/writing-changelog.md | 29 +++++++++++++------ 1 file changed, 20 insertions(+), 9 deletions(-) diff --git a/src/handbook/engineering/releases/writing-changelog.md b/src/handbook/engineering/releases/writing-changelog.md index 17c27289ac..477366a829 100644 --- a/src/handbook/engineering/releases/writing-changelog.md +++ b/src/handbook/engineering/releases/writing-changelog.md @@ -6,7 +6,7 @@ navTitle: 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 a FlowFuse user, someone who is busy and wants to quickly understand what changed and whether it affects them. +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 @@ -14,8 +14,7 @@ Write a changelog post when you ship something a user would notice or benefit fr 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 not, skip it. - +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 @@ -27,7 +26,6 @@ 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: @@ -41,6 +39,24 @@ Every post requires the following fields at the top of the file: | `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. +date: YYYY-MM-DD +authors: your-handle +tags: + - changelog +issues: + - https://github.com/FlowFuse//issues/ +--- + +Write the changelog post here. +``` ## Writing the post @@ -73,7 +89,6 @@ If a feature is only available on certain plans or from a specific version, say If a change could break an existing user setup or requires action before upgrading, say so in the first paragraph. Do not bury it. - ## 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. @@ -96,7 +111,6 @@ Avoid jargon unless it is standard FlowFuse or Node-RED vocabulary. If a technic 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 @@ -123,7 +137,6 @@ Short, honest about the size of the change, and gets straight to the point. 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. @@ -134,7 +147,6 @@ Instead of describing the feature abstractly, this shows exactly how a user will 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. @@ -147,7 +159,6 @@ The technical detail is there, but the sentence that follows immediately transla 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 at least one other team member before merging. From 4dfd44d86660633c9de03a43acc509528844026d Mon Sep 17 00:00:00 2001 From: "sumit shinde ( Roni )" <110285294+sumitshinde-84@users.noreply.github.com> Date: Mon, 16 Mar 2026 22:03:02 +0530 Subject: [PATCH 08/23] Update writing-changelog.md --- .../engineering/releases/writing-changelog.md | 37 +++++++++++++++++-- 1 file changed, 33 insertions(+), 4 deletions(-) diff --git a/src/handbook/engineering/releases/writing-changelog.md b/src/handbook/engineering/releases/writing-changelog.md index 477366a829..a5d3e098f3 100644 --- a/src/handbook/engineering/releases/writing-changelog.md +++ b/src/handbook/engineering/releases/writing-changelog.md @@ -43,10 +43,11 @@ Every post requires the following fields at the top of the file: You can start a new changelog post with the following template: +```markdown ```markdown --- title: Short Feature Title -description: One sentence summarising the change. +description: One sentence summarising the change — written for a user, not an engineer. date: YYYY-MM-DD authors: your-handle tags: @@ -55,7 +56,36 @@ issues: - https://github.com/FlowFuse//issues/ --- -Write the changelog post here. + + +[What changed, stated plainly.] + + + +[The problem this solves or the benefit it brings.] + + + +To get started: + +1. [First step] +2. [Second step] + + + +![Alt text describing the UI shown](./images/your-image.png) +*Caption describing what is shown in context.* + + + +This feature is available to [plan/tier] users of FlowFuse Cloud and [licence type] Self Hosted users from [vX.Y]. ``` ## Writing the post @@ -123,7 +153,6 @@ Do not paste PR titles or commit messages. They are written for engineers. Rewri 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: @@ -161,4 +190,4 @@ State what is changing and who it affects in the first sentence. Then explain wh ## 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 at least one other team member before merging. +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. From 41e605da5219e91b98afb63ca94e6eb7d41a17bc Mon Sep 17 00:00:00 2001 From: "sumit shinde ( Roni )" <110285294+sumitshinde-84@users.noreply.github.com> Date: Mon, 16 Mar 2026 22:08:15 +0530 Subject: [PATCH 09/23] add CODEOWNERS rule for changelog posts --- CODEOWNERS | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CODEOWNERS b/CODEOWNERS index ef2a55a86d..31088a19f2 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -22,3 +22,6 @@ # 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 From dd7c4239b80fa67d932f9db921520993e01ea335 Mon Sep 17 00:00:00 2001 From: "sumit shinde ( Roni )" <110285294+sumitshinde-84@users.noreply.github.com> Date: Mon, 16 Mar 2026 22:08:58 +0530 Subject: [PATCH 10/23] Update CODEOWNERS --- CODEOWNERS | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/CODEOWNERS b/CODEOWNERS index 31088a19f2..f8c547df0d 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -19,9 +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 +/handbook/engineering/releases/writing-changelog @sumitshinde-84 @dimitrieh From d501aef7653f3f112e9ef97f31ceb838b4a3c46a Mon Sep 17 00:00:00 2001 From: "sumit shinde ( Roni )" <110285294+sumitshinde-84@users.noreply.github.com> Date: Wed, 18 Mar 2026 14:59:37 +0530 Subject: [PATCH 11/23] Update writing-changelog.md --- src/handbook/engineering/releases/writing-changelog.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/handbook/engineering/releases/writing-changelog.md b/src/handbook/engineering/releases/writing-changelog.md index a5d3e098f3..e6ecebb443 100644 --- a/src/handbook/engineering/releases/writing-changelog.md +++ b/src/handbook/engineering/releases/writing-changelog.md @@ -111,6 +111,8 @@ Include a screenshot for any visual change. Reference images from `src/img/` lik 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 be 1408px wide to support retina screens. Height can vary depending on what is being shown. + ### Availability If a feature is only available on certain plans or from a specific version, say so. Put this at the end of the post, or immediately after the main announcement if it affects whether the user can access it at all. From 763687bd7a35161be1d25e7750cd97b7710246a2 Mon Sep 17 00:00:00 2001 From: "sumit shinde ( Roni )" <110285294+sumitshinde-84@users.noreply.github.com> Date: Wed, 18 Mar 2026 15:01:21 +0530 Subject: [PATCH 12/23] Update writing-changelog.md --- src/handbook/engineering/releases/writing-changelog.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/handbook/engineering/releases/writing-changelog.md b/src/handbook/engineering/releases/writing-changelog.md index e6ecebb443..1a97a2a19c 100644 --- a/src/handbook/engineering/releases/writing-changelog.md +++ b/src/handbook/engineering/releases/writing-changelog.md @@ -111,7 +111,7 @@ Include a screenshot for any visual change. Reference images from `src/img/` lik 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 be 1408px wide to support retina screens. Height can vary depending on what is being shown. +Screenshots should ideally be 1408px wide. Height can vary depending on what is being shown. ### Availability From af2fd9c2d36a96c10dfd4b984bb775c193815cc6 Mon Sep 17 00:00:00 2001 From: "sumit shinde ( Roni )" <110285294+sumitshinde-84@users.noreply.github.com> Date: Wed, 18 Mar 2026 15:03:16 +0530 Subject: [PATCH 13/23] Update writing-changelog.md --- src/handbook/engineering/releases/writing-changelog.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/handbook/engineering/releases/writing-changelog.md b/src/handbook/engineering/releases/writing-changelog.md index 1a97a2a19c..a66e750130 100644 --- a/src/handbook/engineering/releases/writing-changelog.md +++ b/src/handbook/engineering/releases/writing-changelog.md @@ -151,7 +151,7 @@ Do not paste PR titles or commit messages. They are written for engineers. Rewri > > 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/)* +*Source: [Duplicate Instances Across Different Applications](/changelog/2025/10/duplicate-instances-across-applications/)* Short, honest about the size of the change, and gets straight to the point. @@ -164,7 +164,7 @@ Short, honest about the size of the change, and gets straight to the point. > - 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/)* +*Source: [FlowFuse Expert: Palette Queries](/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. @@ -174,7 +174,7 @@ Instead of describing the feature abstractly, this shows exactly how a user will > > 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/)* +*Source: [HA Hosted Instance Rolling Restart](/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*. @@ -186,7 +186,7 @@ The technical detail is there, but the sentence that follows immediately transla > > To check your current version, run `node --version`. -*Source: [Node.js v20 Minimum Version Requirement](https://flowfuse.com/changelog/2025/11/minimum-nodejs-version/)* +*Source: [Node.js v20 Minimum Version Requirement](/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. From 1f5cf01afa8518f9ebac5f806b2a02ea44520bf1 Mon Sep 17 00:00:00 2001 From: "sumit shinde ( Roni )" <110285294+sumitshinde-84@users.noreply.github.com> Date: Wed, 18 Mar 2026 15:34:39 +0530 Subject: [PATCH 14/23] Update writing-changelog.md --- .../engineering/releases/writing-changelog.md | 37 ++++++++++++++----- 1 file changed, 27 insertions(+), 10 deletions(-) diff --git a/src/handbook/engineering/releases/writing-changelog.md b/src/handbook/engineering/releases/writing-changelog.md index a66e750130..8644abd10c 100644 --- a/src/handbook/engineering/releases/writing-changelog.md +++ b/src/handbook/engineering/releases/writing-changelog.md @@ -14,7 +14,7 @@ Write a changelog post when you ship something a user would notice or benefit fr 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. +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 @@ -43,11 +43,10 @@ Every post requires the following fields at the top of the file: You can start a new changelog post with the following template: -```markdown ```markdown --- title: Short Feature Title -description: One sentence summarising the change — written for a user, not an engineer. +description: One sentence summarising the change, written for a user, not an engineer. date: YYYY-MM-DD authors: your-handle tags: @@ -111,11 +110,29 @@ Include a screenshot for any visual change. Reference images from `src/img/` lik 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. +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: -### Availability +> This feature is available to Enterprise tier users of FlowFuse Cloud and Enterprise Licensed Self Hosted users from vX.Y. -If a feature is only available on certain plans or from a specific version, say so. Put this at the end of the post, or immediately after the main announcement if it affects whether the user can access it at all. +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. ### Breaking changes @@ -151,7 +168,7 @@ Do not paste PR titles or commit messages. They are written for engineers. Rewri > > It is a small (but important) improvement that just makes things that little bit easier. -*Source: [Duplicate Instances Across Different Applications](/changelog/2025/10/duplicate-instances-across-applications/)* +*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. @@ -164,7 +181,7 @@ Short, honest about the size of the change, and gets straight to the point. > - 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](/changelog/2026/01/ff-expert-palette-queries/)* +*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. @@ -174,7 +191,7 @@ Instead of describing the feature abstractly, this shows exactly how a user will > > This feature is available to Enterprise Licensed Self Hosted users and Enterprise tier users of FlowFuse Cloud. -*Source: [HA Hosted Instance Rolling Restart](/changelog/2026/02/ha-instance-rolling-restart/)* +*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*. @@ -186,7 +203,7 @@ The technical detail is there, but the sentence that follows immediately transla > > To check your current version, run `node --version`. -*Source: [Node.js v20 Minimum Version Requirement](/changelog/2025/11/minimum-nodejs-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. From 87de2ef2f95db0059565baead8279f26abb212d1 Mon Sep 17 00:00:00 2001 From: "sumit shinde ( Roni )" <110285294+sumitshinde-84@users.noreply.github.com> Date: Wed, 18 Mar 2026 16:34:10 +0530 Subject: [PATCH 15/23] Update writing-changelog.md --- src/handbook/engineering/releases/writing-changelog.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/src/handbook/engineering/releases/writing-changelog.md b/src/handbook/engineering/releases/writing-changelog.md index 8644abd10c..c33d69d415 100644 --- a/src/handbook/engineering/releases/writing-changelog.md +++ b/src/handbook/engineering/releases/writing-changelog.md @@ -134,10 +134,6 @@ Always write an availability note in the post as well. Tier badges communicate t 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. -### Breaking changes - -If a change could break an existing user setup or requires action before upgrading, say so in the first paragraph. Do not bury it. - ## 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. From 04a184e4c612121477656d4660a3352e666b1ad0 Mon Sep 17 00:00:00 2001 From: "sumit shinde ( Roni )" <110285294+sumitshinde-84@users.noreply.github.com> Date: Wed, 25 Mar 2026 18:34:48 +0530 Subject: [PATCH 16/23] Apply suggestions from code review Co-authored-by: Jamie Strusz <5758031+allthedoll@users.noreply.github.com> --- .../engineering/releases/writing-changelog.md | 41 ++++++++++++++++++- 1 file changed, 39 insertions(+), 2 deletions(-) diff --git a/src/handbook/engineering/releases/writing-changelog.md b/src/handbook/engineering/releases/writing-changelog.md index c33d69d415..280d059d16 100644 --- a/src/handbook/engineering/releases/writing-changelog.md +++ b/src/handbook/engineering/releases/writing-changelog.md @@ -16,6 +16,14 @@ Do not write changelog posts for internal tooling changes with no user-visible i 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. +## 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. ## 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. @@ -91,7 +99,7 @@ This feature is available to [plan/tier] users of FlowFuse Cloud and [licence ty 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: +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. @@ -99,6 +107,8 @@ That said, every post should answer three questions: **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: @@ -138,6 +148,7 @@ Put it at the end of the post, or immediately after the main announcement if it 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 | @@ -156,6 +167,25 @@ Avoid jargon unless it is standard FlowFuse or Node-RED vocabulary. If a technic Do not paste PR titles or commit messages. They are written for engineers. 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 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. ## Examples ### A small but useful improvement @@ -205,4 +235,11 @@ State what is changing and who it affects in the first sentence. Then explain wh ## 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. +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. From 0aa4989c1be025353bedc52ccfc2ba6f0b07e344 Mon Sep 17 00:00:00 2001 From: "sumit shinde ( Roni )" <110285294+sumitshinde-84@users.noreply.github.com> Date: Wed, 25 Mar 2026 18:38:57 +0530 Subject: [PATCH 17/23] Update CODEOWNERS --- CODEOWNERS | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CODEOWNERS b/CODEOWNERS index f8c547df0d..72af2eb88e 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -23,4 +23,4 @@ /package-lock.json @FlowFuse/engineering @Yndira-E # Changelog posts (tech writer required, product as backup) -/handbook/engineering/releases/writing-changelog @sumitshinde-84 @dimitrieh +/handbook/engineering/releases/writing-changelog @sumitshinde-84 @dimitrieh @allthedoll From 2f6bb05f71281642c4815e9e8e84c20d7a550635 Mon Sep 17 00:00:00 2001 From: "sumit shinde ( Roni )" <110285294+sumitshinde-84@users.noreply.github.com> Date: Wed, 25 Mar 2026 18:39:50 +0530 Subject: [PATCH 18/23] Update src/handbook/engineering/releases/writing-changelog.md Co-authored-by: Jamie Strusz <5758031+allthedoll@users.noreply.github.com> --- src/handbook/engineering/releases/writing-changelog.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/handbook/engineering/releases/writing-changelog.md b/src/handbook/engineering/releases/writing-changelog.md index 280d059d16..975e50ac5a 100644 --- a/src/handbook/engineering/releases/writing-changelog.md +++ b/src/handbook/engineering/releases/writing-changelog.md @@ -10,7 +10,9 @@ A changelog post is not a PR description or a release note. It is a short, focus ## 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. +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. From 9a8574bd936ade59e9a18dc92edb53a9cdd49863 Mon Sep 17 00:00:00 2001 From: "sumit shinde ( Roni )" <110285294+sumitshinde-84@users.noreply.github.com> Date: Wed, 25 Mar 2026 18:41:16 +0530 Subject: [PATCH 19/23] Update CODEOWNERS --- CODEOWNERS | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CODEOWNERS b/CODEOWNERS index 72af2eb88e..8191d70840 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -23,4 +23,4 @@ /package-lock.json @FlowFuse/engineering @Yndira-E # Changelog posts (tech writer required, product as backup) -/handbook/engineering/releases/writing-changelog @sumitshinde-84 @dimitrieh @allthedoll +/handbook/engineering/releases/writing-changelog @FlowFuse/marketing @FlowFuse/product @FlowFuse/engineering From 5b0ce7c538d577726c1b0254d77741f8e70d7047 Mon Sep 17 00:00:00 2001 From: "sumit shinde ( Roni )" <110285294+sumitshinde-84@users.noreply.github.com> Date: Thu, 26 Mar 2026 16:37:17 +0530 Subject: [PATCH 20/23] Update writing-changelog.md --- src/handbook/engineering/releases/writing-changelog.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/handbook/engineering/releases/writing-changelog.md b/src/handbook/engineering/releases/writing-changelog.md index 975e50ac5a..58f942e2eb 100644 --- a/src/handbook/engineering/releases/writing-changelog.md +++ b/src/handbook/engineering/releases/writing-changelog.md @@ -44,7 +44,7 @@ Every post requires the following fields at the top of the file: |---|---| | `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. | +| `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 multiple features are added 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 being announced. | @@ -57,7 +57,7 @@ You can start a new changelog post with the following template: --- title: Short Feature Title description: One sentence summarising the change, written for a user, not an engineer. -date: YYYY-MM-DD +date: YYYY-MM-DD HH:mm:ss authors: your-handle tags: - changelog From 994cb44a3a9c13d66430497a3b865db37aa24355 Mon Sep 17 00:00:00 2001 From: Jamie Strusz <5758031+allthedoll@users.noreply.github.com> Date: Mon, 30 Mar 2026 10:13:50 +0100 Subject: [PATCH 21/23] Final tweaks for passive to active voice --- .../engineering/releases/writing-changelog.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/handbook/engineering/releases/writing-changelog.md b/src/handbook/engineering/releases/writing-changelog.md index 58f942e2eb..a1ceb96bec 100644 --- a/src/handbook/engineering/releases/writing-changelog.md +++ b/src/handbook/engineering/releases/writing-changelog.md @@ -18,14 +18,14 @@ Do not write changelog posts for internal tooling changes with no user-visible i 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. -## How changelog posts are triggered +## Identifying what needs a changelog post -Changelog posts should be identified during refinement, not after work is complete. +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 changelog work is planned alongside delivery, rather than being remembered (or missed) at release time. +This ensures changelog work is planned alongside delivery, rather than remembered (or missed) 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. @@ -136,9 +136,9 @@ changelog: 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. +Once that entry is in place, the build injects tier availability badges into the changelog post automatically. 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. +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: @@ -239,7 +239,7 @@ State what is changing and who it affects in the first sentence. Then explain wh 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: +Have at least one of the following review the post before it goes live: - Product - Marketing - Engineering From 0c215cd45bb5d653a80d4a8b48f869827205c534 Mon Sep 17 00:00:00 2001 From: Jamie Strusz <5758031+allthedoll@users.noreply.github.com> Date: Mon, 30 Mar 2026 11:02:58 +0100 Subject: [PATCH 22/23] More passive to active voice --- .../engineering/releases/writing-changelog.md | 23 ++++++++++--------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/src/handbook/engineering/releases/writing-changelog.md b/src/handbook/engineering/releases/writing-changelog.md index a1ceb96bec..ceeae7c3a0 100644 --- a/src/handbook/engineering/releases/writing-changelog.md +++ b/src/handbook/engineering/releases/writing-changelog.md @@ -16,7 +16,7 @@ This includes new features, meaningful improvements to existing functionality, b 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. +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 @@ -25,7 +25,8 @@ Product and engineering identify changelog posts during refinement, not after wo - 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 remembered (or missed) at release time. +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. @@ -34,7 +35,7 @@ Posts live in the [website repository](https://github.com/FlowFuse/website/tree/ src/changelog/YYYY/MM/your-post-slug.md ``` -The slug should be short, lowercase, and hyphen-separated, describing the feature being announced. +The slug should be short, lowercase, and hyphen-separated, describing the feature you are announcing. ## Frontmatter @@ -44,10 +45,10 @@ Every post requires the following fields at the top of the file: |---|---| | `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 multiple features are added on the same day. | +| `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 being announced. | +| `issues` | A list of related GitHub issue URLs. Link any issues that tracked the work this post announces. | ## Starting Template @@ -120,13 +121,13 @@ Include a screenshot for any visual change. Reference images from `src/img/` lik *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. +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 is being shown. +Screenshots should ideally be **1408px wide**. Height can vary depending on what you are showing. ### 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. +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: @@ -136,7 +137,7 @@ changelog: release: "2.29" ``` -Once that entry is in place, the build injects tier availability badges into the changelog post automatically. No additional markup needed in the post itself. +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. @@ -167,7 +168,7 @@ Keep it short. A changelog post is not a blog post. If the feature needs more de 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. +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 @@ -211,7 +212,7 @@ Short, honest about the size of the change, and gets straight to the point. *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. +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 From 2473458f5fd1d48ab2252e5a5d9c363cb5e6b8d5 Mon Sep 17 00:00:00 2001 From: Jamie Strusz <5758031+allthedoll@users.noreply.github.com> Date: Mon, 30 Mar 2026 11:10:27 +0100 Subject: [PATCH 23/23] More passive to active language --- src/handbook/engineering/releases/writing-changelog.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/handbook/engineering/releases/writing-changelog.md b/src/handbook/engineering/releases/writing-changelog.md index ceeae7c3a0..8fbd840a04 100644 --- a/src/handbook/engineering/releases/writing-changelog.md +++ b/src/handbook/engineering/releases/writing-changelog.md @@ -6,7 +6,7 @@ navTitle: 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. +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 @@ -14,7 +14,7 @@ Write a changelog post when you ship something a user would notice or benefit fr 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. +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. @@ -81,7 +81,7 @@ issues: [The problem this solves or the benefit it brings.] - + To get started: @@ -180,7 +180,7 @@ Paste the following prompt into your tool of choice along with your PR descripti > - 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 +> - 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.