handbook: add guide for writing changelog posts#4674
handbook: add guide for writing changelog posts#4674sumitshinde-84 wants to merge 17 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. |
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