API and deprecation policy

[oliverklee]

Hi @JakeQZ and @sabberworm, in light of #704, I'd like to suggest a (new) API and deprecation policy for this project and for our sister project Emogrifier. What do you think?

API policy

The code of this library is intended to be called in other projects. It's not intended to be extended. If you want to extend any classes, you're on your own, and your code might break with any new release of this library.

Any classes, methods and properties that are public and not marked as @internal are considered to be API. Those methods will continue working in a compatible way over minor and bug-fix releases according to Semantic Versioning. we might change the native type declarations in a way that might break subclasses, though.

Any classes, methods and properties that are protected or private are not considered API. Please do not rely on them. If you do, you're on your own.

Any code that is marked as @internal is subject to be changed or removed without notice. Please do not call it. There be dragons.

If a class is marked as @internal, all properties and methods of this class are by definition to be considered to be internal as well.

When we change some code from public to @internal in a release, the first release that might change that code in a breaking way will be the next major release after that. This will allow you to change your code accordingly.

For example, we might mark some code as @internal in version 8.6.1. The first version that possibly changes this code in a breaking way then will be version 9.0.0.

Before you upgrade your code to the next major version of this library, please update to the latest release of the previous major version and make sure that your code does not reference and code that is marked as @internal.

Deprecation policy

Code that we plan to remove is marked as @deprecated. In the corresponding annotation, we also note in which release the code will be removed.

When we mark some code as @deprecated in a release, we'll usually remove it in the next major release.

For example, when we mark some code as @deprecated in version 8.6.1, we'll remove it in version 9.0.0 (or sometimes a later major release).

Before you upgrade your code to the next major version of this library, please update to the latest release of the previous major version and make sure that your code does not reference and code that is marked as @deprecated.

[oliverklee]

I’d also welcome any ides on how to make this text easier to understand, and I’d also highly welcome a make-over by @JakeQZ (as a native speaker). 🙏

[JakeQZ]

The policy seems fine to me, except that Semantic Versioning says:

Minor version Y (x.Y.z | x > 0) ... MUST be incremented if any public API functionality is marked as deprecated.

So...

For example, we might mark some code as @internal in version 8.6.1. The first version that possibly changes this code in a breaking way then will be version 9.0.0.

The example version should be at least a new minor release, e.g. 8.7.0.

For example, when we mark some code as @deprecated in version 8.6.1, we'll remove it in version 9.0.0 (or sometimes a later major release).

Again, the example version should be e.g. 8.7.0.

I'll look at the English separately.

[JakeQZ]

It's not intended to be extended. If you want to extend any classes, you're on your own

This is OK provided there aren't any existing classes that were designed to be extended.

[JakeQZ]

I think these changes to the wording would make it clearer and/or grammatically correct. I've clarified the suggested changes with bold italic - I'm not saying these words should be in bold italic.

The code of this library is intended to be called in other projects.

The code in this library is intended to be called by other projects.

It's not intended to be extended.

It is not ...

[more formal and stands out more]

Any classes, methods and properties that are public and not marked as @internal are considered to be API.

... considered to be part of the API.

Those methods will continue working in a compatible way over minor and bug-fix releases according to Semantic Versioning. we might change the native type declarations in a way that might break subclasses, though.

... according to Semantic Versioning, though we might change the native type declarations in a way that could break subclasses.

[also removing final "though" - note comma after "Semantic Versioning"]

Any classes, methods and properties that are protected or private are not considered API. Please do not rely on them. If you do, you're on your own.

... not considered part of the API.

Any code that is marked as @internal is subject to be changed or removed without notice. Please do not call it. There be dragons.

subject to change or removal without notice.

If a class is marked as @internal, all properties and methods of this class are by definition to be considered to be internal as well.

... are by definition considered to be internal as well.

[remove first "to be"]

For example, we might mark some code as @internal in version 8.6.1.

@internal

[remove extra space within backticks]

The first version that possibly changes this code in a breaking way then will be version 9.0.0.

... in a breaking way will then be version 9.0.0.

Before you upgrade your code to the next major version of this library, please update to the latest release of the previous major version and make sure that your code does not reference and code that is marked as @internal.

... reference any code ...

Before you upgrade your code to the next major version of this library, please update to the latest release of the previous major version and make sure that your code does not reference and code that is marked as @deprecated.

... reference any code ...

[JakeQZ]

With this policy, we should probably revert MyIntervals/emogrifier#103.

[oliverklee]

I've created a ticket for that: MyIntervals/emogrifier#1309

[oliverklee]

This is now merged. Hence closing this discussion.