You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
I've copied the full text of the thread below for recreation BUT the short version is that a word at the start of a paragraph got split between its first and second letter. it may be related to the fact that it's all caps.
HOWEVER the regexp should be modified such that it NEVER breaks when there's a word character following immediately after the potential break point.
@iamada@tech.lgbt 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.
---
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.
----
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.
---
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.
----
Third, tooling:
You NEVER want autogenerated chaneglogs (blog post why: https://weblog.masukomi.org/2016/06/30/why-you-cant-auto-generate-your-changelog/ )
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.
---
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.
Related: Blog post on creating great changelogs.
https://weblog.masukomi.org/2016/07/03/keeping-a-great-changelog/
The text was updated successfully, but these errors were encountered:
I've copied the full text of the thread below for recreation BUT the short version is that a word at the start of a paragraph got split between its first and second letter. it may be related to the fact that it's all caps.
HOWEVER the regexp should be modified such that it NEVER breaks when there's a word character following immediately after the potential break point.
The text was updated successfully, but these errors were encountered: