@iamada Tooted a bit ago about troubles getting their developers to contribute to a changelog.
I used to be a release manager at one co. I know the pain well, and i have a LOT of thoughts on it.
The short answer is that as much as we wish they would update one with / for each PR they wont, and if you're talking about literally editing a CHANGELOG file then you DEFINITELY do NOT want them to try.
🧵1/7
the naïve approach of "just add your changelog message to the bottom of the file" will end with yelling and / or tears because of the CONSTANT merge conflicts it'll generate. It's just not practically possible. Don't go there.
BUT there are multiple bigger problems with developers making changelog entries, even if you had a technically feasible mechanism.
🧵2/7
First, they're thinking at the wrong level of abstraction. They rarely have the skill / experience to consider what they did in code, and reframe it in such a way that the person who needs to read the changelog has the right level of detail & terminology. You'll get a changelog, but the stakeholders and/or customers who would benefit from reading a good one will either find it gibberish OR statements about code that they understand but without the context to make it meaningful.
🧵3/7
Second, in some cases there needs to be 1 changelog for internal stakeholders and a completely different changelog for customers. Again, each one needs a different level of abstraction because they are working from different contexts.
🧵4/7
If you decided to use ANY Of the tools that have been written (i even made one) that allow developers to record an entry for a changelog that is also somehow tied to the PR you will have a fucking mutiny over getting them to adopt it into their workflow.
🧵5/7
AND even if your team is like the unique magical unicorn capable of understand the value of the task, you've still got the abstraction problem.
My best advice for addressing this problem is to (with their input) modify the template you're using for PR descriptions to have a heading that says something like "At a high level, describe what you did in 1 or 2 sentences" followed by whatever details are needed for the other geeks to understand & review the PR.
THEN you, the release manager, or anyone on the team who can put themselves in the reader's shoes... sits down, goes through all the PRs in the release, and rewrites all the geeky sentences into something that's more concise and conveys the right level of info for the reader.
Add comment