New automerge requirement: Release notes required for breaking package releases

Package Announcements
,
41

like I said before, the users need to provide the incentive by preferring packages >=1.0

it is a balance

  • users prefer packages >=1.0 because they come with greater API documentation and stability guarantees
  • developers prefer packages >=1.0 so that they can attract more users

when there are policies (such as the one that’s been added here) to enforce greater API documentation and stability guarantees to pre-1.0 packages, the first incentive falls apart and thus so does too the second.

42

Actually, I think that this new policy is a great incentive to go v1.x.y

IMO, the off-by-one semVer is (was for me) a big annoyance. See, according to it in the v0.x.y stage raising x means a breaking change. So, either bug fixes or new features have to be accommodated in changing y. Sorry, but this is a complete nonsense to me, and I never followed it (and bet I’m not alooooone)

Now, with the new policy, this semVer strictness will be enforced to everyone. So all those (like me) that increase x for new features will be very annoyed with automatic refusals because they are not logging the breaking changes … but they are none because they were really nor following semVer here.

But life will be much easier on a v>=1.x.y world where breaking changes are real breaking changes (increasing MAJOR number) and new features are peacefully landing in x increases.

43

I think I recall a proposal by @oxinabox , to require packages registered in General to have a version >= 1.0.0. We could have another auto-merge rule that enforces this. I always thought that was a good idea.

3 Likes
44

That‘s the thing. I don‘t think these market forces can really work. If I need some package, especially if it is well-established in the Julia ecosystem and could well be v1 already, I‘m not going to not depend on it only because it hasn‘t. For that to be an option, there would need to be an alternative package that can provide close to the same features while being even more mature etc.

5 Likes
45

Hi!

What about packages that are pre-1.0 and we want to increase the version to 1.0 (declaring it stable)?

I have a package that the current version is 0.1.8. The API is very stable, has not changed in years, and I am ready to move the version to 1.0.0. However, there was no breaking changes! What should I do to comply with the new guideline?

1 Like
46

Presumably add a section like

## Breaking changes

There are no breaking changes. This release is a version bump to v1.0.0 only.
6 Likes
47

Oh! Ok :smiley: Thanks!

48

I am a strong advocate of the idea that 1.0 releases should not include breaking changes, but should be tagged exactly like you did here: when the API is deemed to be stable.

So, we’ve just added an unnecessary stumbling block to packages moving from 0.x to 1.0, which is something we all agreed is desirable. Now everyone will be pushed to think that a 1.0 release must include a breaking change, which then raises the question “why is this particular breaking change important enough to warrant 1.0”. That kind of decision paralysis is exactly how we get stuck in the zerover dilemma.

So can we PLEASE roll back the requirement that release notes must include specific phrases?

1 Like
49

Whenever Pkg treats two versions as incompatible, you should specify what is or is not incompatible so your users know how to update their code. That doesn’t seem wrong to me even for this situation.

8 Likes
50

I agree, but I don’t like the idea of having to go out of my way to use specific words in the changelog, just to make a bot happy. “The API is now considered stable. Version 1.0 is functionally identical to v0.3” seems like a perfectly fine release note. So is “See CHANGELOG.md for release notes”, generally. Now I have to figure out how to add a sentence or change the phrasing so that the word “breaking” appears. And worse, as I was trying to point out, this can then create false incentives, like not wanting to tag v1.0.

The specific wording of a changelog is just something that’s highly context-dependent and not easily delegated to a bot. I think it’s sufficient to check for the existence of release notes, combined with guidelines on what we expect from such release notes, namely that they give instructions on how to adapt to breaking changes. And, in fact: just because the word “breaking” appears, that’s no guarantee that any such instruction are part of the notes. So I completely agree on the underlying motivation, I just think that checking for specific words is too crude a tool.

4 Likes
51

I agree it’s a bit inflexible, and maybe we can improve it, but this actually works as-is: changelog and breaking are the two keywords it looks for currently.

1 Like