Add a checklist of things to do before tagging a breaking release?

[oxinabox]

There are some things that should be done before tagging a breaking release. This is what i have so far:

• Are you sure this is breaking? Tagging breaking releases that are not actually breaking just adds work for everyone.
• Increment version number / remove -DEV suffix
• Delete any deprecations added since last nonbreaking release (don't forget to search for uses of depwarn that might be scattered in the code)
• Write release notes and/or upgrading guide if appropriate.

[ChrisRackauckas]

Delete any deprecations added since last nonbreaking release (don't forget to search for uses of depwarn that might be scattered in the code)

Ehh not too keen on this wording. Delete any deprecations you wish to delete before the breaking release, but I don't think it's always good practice to delete all. In some cases, keeping a deprecation around for a fixed time (a year or so) can be better practice depending on how things are moving.

[YingboMa]

Maybe force to print the deprecation? Julia now hides depwarns by default.

[devmotion]

Julia now hides depwarns by default.

Not in the tests though.

[ali-ramadhan]

Write release notes and/or upgrading guide if appropriate.

Should the release notes contain a list of the breaking changes at the top?

I think this is super helpful for users updating their scripts/packages.

[oxinabox]

Delete any deprecations added since last nonbreaking release (don't forget to search for uses of depwarn that might be scattered in the code)

Ehh not too keen on this wording. Delete any deprecations you wish to delete before the breaking release, but I don't think it's always good practice to delete all. In some cases, keeping a deprecation around for a fixed time (a year or so) can be better practice depending on how things are moving.

Alternate wording:

• Ensure that deprecations should have been removed have been (don't forget to search for uses of depwarn that might be scattered in the code)
  • usually this means there should be no deprecations in a freshly tagged breaking version, as you can remove them as part of the breaking change.
  • sometimes there are exceptions to this, e.g. keeping things around for longer to allow more time to move over to the new way.

OTOH: maybe we shouldn't bother. Exceptions are exceptional. So we don't write for them.

The use of the word MUST, SHOULD and MAY in this document are per RFC 2119. (I don't know that that is mentioned but in drafting it i was fairly careful about that) Which has:

3. SHOULD This word, or the adjective "RECOMMENDED", mean that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course.

So we can say: you should follow this check-list. And exceptions are exceptions.

[ChrisRackauckas]

But keeping deprecations isn't an exception, it's a norm unless there's a longer release process.

[oxinabox]

Ok, I will make some wording that highlights these two options to be balanced. And the check list will say something about removing the appropriate ones. I think that will resolve that.

Anything else for the check-list?

[ChrisRackauckas]

I would add that deprecation warnings shouldn't be deleted in less than a year. I've seen things where deprecation warnings get deleted within a month or two, and at that point it essentially doesn't exist. Dev practices shouldn't require that the users are using the package weekly in order for them to work. There's definitely a level which is bigger than a day and shorter than 5 years, and people might place the line in a different spot, but one year is about right to me.

[oxinabox]

Yeah I will put that that in the description. Probably in particular for package that are post-1.0. (It's kinda what 1.0 means, I promise I won't break your stuff for a while. Ideally wouldn't even be releasing a breaking change more than once a year) It's a bit strong for a package that is at 0.x.