Remark: Release notes for major release?

[jescalan]

A major release just came out, which generally means to be careful upgrading as there are breaking changes. However, the release notes are very vague and do not detail whether there actually were breaking changes, and if so, what to do to fix them. I'd be happy to contribute in any way here, but it would be super helpful to get a little more detail here so I can feel more confident updating the version!

[wooorm]

Hi Jeff!

remark/unified is an intricate system used by millions. Therefore we’re extra careful with potential breaking changes. In this case, your code probably works, unless you’re using typescript. Everything else is fixes, that could break.

I’m confident your code will work as-is, but there could be some small changes (due to fixes), potentially breaking your build, or adding a message here or there.

[jescalan]

So basically, it is definitely a breaking change if you're using typescript, and you don't really know if it's a breaking change if not, but you think that probably it isn't? This is definitely more helpful than nothing at least! Thank you

[wooorm]

you don't really know if it's a breaking change

This really depends on how you use remark, if you could expand on that, we can judge better whether it’ll break or not. Because it depends, better safe than sorry, so a major release.

In unified’s lifetime, we’ve experienced that adding types can break peoples build. Even if that’s just 1k out of 1m people, that’s a lot of people. One example of this is that unified/remark is used in stylelint (and many other build tools), and that typescript for some reason seems to load every type definition file in node_modules, and fails if you’re on an older typescript than used in unified/remark.
The same goes for any syntax change we make. Even if it’s a fix, it’ll likely break someone’s build.

[vweevers]

However, the release notes are very vague and do not detail whether there actually were breaking changes, and if so, what to do to fix them.

@wooorm I second this, for multiple past releases in the unified ecosystem. If I, as a consumer, get notified about a semver-major release, I assume there is a breaking change that needs my attention, and I go looking for instructions in the release notes.

If the release notes stated something like "Add TypeScript definitions (breaking)", I would immediately update, knowing that the breaking change does not apply to me because I'm not a TS user.

As for bugfixes that could break people's builds: that's true for any project. A consumer can asses the risk of that and lock dependency versions accordingly. Personally I prefer taking risk over having to review every release. And to mitigate some of that risk, using tools like Greenkeeper to run unit tests whenever a dependency is updated in-range.

I can see though why a commit like https://github.com/remarkjs/remark/commit/628205195976c4ccc2f4b333b32d7308ad8192dc isn't semver-patch. Judging by the commit description this isn't just a bugfix. So to more clearly communicate that fact, I would suggest writing "Change xy" in the commit title (and thus release notes) rather than "_Fix_ xy".

[wooorm]

As for bugfixes that could break people's builds: that's true for any project. A consumer can asses the risk of that and lock dependency versions accordingly. Personally I prefer taking risk over having to review every release. And to mitigate some of that risk, using tools like Greenkeeper to run unit tests whenever a dependency is updated in-range.

I somewhat disagree. I, personally, when cutting a release, am responsible for builds that break. As the 400+ projects under unified get a billion downloads a year, the chances of that happening are high. People are rightfully angry when that happens.

I can see though why a commit like 6282051 isn't semver-patch. Judging by the commit description this isn't just a bugfix. So to more clearly communicate that fact, I would suggest writing "Change xy" in the commit title (and thus release notes) rather than "Fix xy".

For this project, a parser/compiler, we promise to support GFM/CM. So my interpretation of a “bug” is something that doesn’t follow that promise. Therefore, in my opinion, this is a fix instead of a change (change is in my understanding of the word more vague than say fix, add, remove, refactor)

I assume there is a breaking change that needs my attention, and I go looking for instructions in the release notes.

I think, from reading them, you were able to figure out there were no API changes.
Or was that hard to figure out?

I’m not sure what you‘re suggesting here, that we stop releasing a major when something can break? That we don‘t follow semver this strictly?

[vweevers]

I, personally, when cutting a release, am responsible for builds that break.

That SLA (so to speak) is your call and it's of a high commendable standard, so on that point I concede.

Just to explain where I was coming from: for the projects I maintain, I'd say the consumers have a responsibility too. If you choose to use my free software, that's awesome and I'll do my best to make your continued use pleasant and free of breakage, but the risk is entirely yours. I treat most of the OSS software that I use in the same way, which means I never have a right to be angry.

I think, from reading them, you were able to figure out there were no API changes.
Or was that hard to figure out?

I wasn't able to figure that out, or at least not before I found this ticket 😉

I’m not sure what you‘re suggesting here, that we stop releasing a major when something can break? That we don‘t follow semver this strictly?

To better communicate the reasons for bumping major. I associate the words "bugfix" and "fix" with semver-patch, so if all entries in the release notes say "Fix xy", that leaves me looking for other explanations for the major bump.

I agree that the word "change" is vague. I did not have a good enough understanding of that commit to find a better verb. Perhaps the solution isn't to change titles of individual changes (because they can easily be misinterpreted, as we see here), but to accompany releases with a summary that explains the major bump.

[vweevers]

but to accompany releases with a summary that explains the major bump

Or to categorize changes, for which there are multiple solutions, from Keep A Changelog to simply placing certain changes under a Breaking header.

[wooorm]

Added a breaking header above the breaking changes, and added a note about the fixes potentially not being breaking in some cases.