I think we should have a call out for intended readers of the changelog. It's not just for customers, but also TS/CSE. Keeping them in mind when writing changelogs will hopefully lead to better changelogs being written at the source of truth.

We only document the HOW here, but including a line about the WHY or WHO would be a good idea imo

🚀

My only comment: there probably should be a facility to not actually require all PRs to result in changelog entries. While every user-facing change should have a changelog, not all commits result in user-facing changes. For example, the use of feature flags to trickle code into main before actually exposing a feature to users is arguably good practice. We're actually doing this right now in the release team, merging appliance-related features into main, but since this is a brand new component, nothing is user-visible yet.

@craigfurman You mentioned commit here, just in case it's not clear, this operates at the PR level, commits are ignored.

I mentioned your question in the FAQ entry already, TL;DR is I'd rather have a changelog in every PR and filter them out at the end, than making folks think whether or not they want to write a changelog entry. I believe that this way, we'll have more of those.

We only document the HOW here, but including a line about the WHY or WHO would be a good idea imo

@Chickensoupwithrice added a quick audience sentence.

@jhchabran ah yes, sorry, I must have missed that in the FAQ. I'll take the conversation to https://www.notion.so/sourcegraph/Writing-a-changelog-entry-dd997f411d524caabf0d8d38a24a878c?pvs=4#833ebe65b29241bc8c11472b8f58d908 since this already merged. I do have a follow-up comment.