API stability policy

[provinzkraut]

Starlite is moving fast, but we currently don't have a policy in place regarding the stability of our API. Our versioning scheme suggests we follow semver, but we have introduced breaking changes in minor versions multiple times.

I'd like to discuss, and in the end introduce, a policy regarding how and when breaking changes occur and how we deal with deprecations. This is an important step, as it will give users the chance to know what they can expect from a new version, when they can safely upgrade and how they need to handle migration in case of breaking changes. Stability of a library is a big factor in deciding for or against it, and we need to address this in a transparent way.

Definition of a breaking change

"Breaking change" in the following means:

• The change / removal of an interface / change of behaviour of an object (function, method, class, etc.) to which any of the following apply and is not explicitly marked as private (i.e. has the canonical _ prefix in its name):
  • It is documented in our reference docs
  • It is available in the starlite namespace or part of a module that is available in the starlite namespace
• The change of user-facing behaviour (i.e JSON responses being serialized differently, change in errors raised, status codes returned, etc.)

Versioning schemes

Strict semver

This would mean we either make sure that all changes that occur in minor or patch releases are backwards compatible, or make major releases more often.

Adapted semver

If we don't follow semver, I'd suggest we establish the following policy:

• MAJOR for fundamental, big changes to the workings of Starlite and / or its interfaces. These should happen rarely
• MINOR for added functionality and changes that might break backwards functionality, but in a way that does not require
  a changing of application logic (i.e. changing a method name is okay, removing that method without offering something that can achieve the same is not). These should occur semi-regularly
• PATCH for bug fixes and backwards compatible changes. This should be the default release type

General migration policy

Deprecations

• Deprecation warnings need to be added for every breaking change that occurs in a MINOR version
• Deprecation warnings can be introduced in either MAJOR or PATCH versions

Clear upgrade paths

Breaking changes must always come with a clear upgrade path, that is, an easy to find document for the user, telling them how they can upgrade from one version to the next.

[Goldziher]

I think the section option is better. But both are viable. We need a checklist before release i think.

[provinzkraut]

I also thinks it fits our current release cadence better. Regarding the checklist, I think it would be helpful if we formalize this policy somewhere, so we can also check for these things during reviews.

[jtraub]

I would vote for the adapted semver. While Starlite doesn't have critical userbase we can conform to this and have higher development velocity.

With the deprecation policy I would suggest that we keep deprecated interfaces/features for given amount of time or number of versions whatever would be longer.

[provinzkraut]

With the deprecation policy I would suggest that we keep deprecated interfaces/features for given amount of time or number of versions whatever would be longer.

I think number of versions would be best, since it's most predictable. Deprecation in three steps seems reasonable.

1. Add PendingDeprecationWarning in a ninor/patch versions
2. Change it to a DeprecationWarning in the next minor version after that
3. Remove functionality in next minor version after that

So it would look for example like this:

1. Add PendingDeprecationWarning in 1.1.1
2. Change to DeprecationWarning in 1.2.0
3. Remove in 1.3.0

Steps 1 + 2 can be automated / enforced by our deprecation utils if we add deprecated_since and removal_in.

[jtraub]

Can we add deprecation notes to the docs based on deprecated_since and removal_in decorators?

[provinzkraut]

Hmm. Should actually not be that difficult. We can just manipulate the __docs__ attribute.

[provinzkraut]

Okay, I checked it and it seems to be a bit more involved, since mkdocstrings doesn't take into account runtime generated docstrings. But I'm sure we can do this somehow. I just assumed we could use the same approach that works for Sphinx 🙃