🔖 Release & declarations lifecycle

[LVMVRQUXL]

3 major versions in one year, that's a lot of changes...

For limiting useless changes and focusing on what matters accordingly to our design goals, we are committing to release:

• one major version maximum per year
• one minor version per quarter
• one patch version per month.

Please note that this library adheres to Semantic Versioning.

This plan will let our team and our community enough time to identify needs and to design the perfect solution to those.
Remember that the perfect system is not the one in which we can't add but the one we can't remove from.

Feel free to comment below if this release cycle suits to your needs, or to suggest a new one that we could discussed with the community.

[LVMVRQUXL]

For users that want an early-access to the features that will be available in each iterations, we are committing to release:

• an alpha version 2 months before the stable release
• a beta version 1 month before the stable release.

[LVMVRQUXL]

We will apply the following versioning strategy and declarations lifecycle starting from version 4.2.

Versioning strategy

Instead of adhering to Semantic Versioning for versioning Kotools Types, we will have a pragmatic approach based on the work needed from consumers to migrate their code:

• a major version introduces changes that will need a lot of effort from consumers to migrate their code
• a minor version introduces changes that will need a little bit of work from consumers to migrate their code
• a patch version introduces changes that will need no work at all from consumers to migrate their code.

The release cycle stays the same: 1 major version maximum per year, 1 minor version per quarter and 1 patch per month.

Declarations lifecycle

Stability stages

In this project, we only use the experimental and the stable stages suggested by the Kotlin team.
By definition, we can update or remove freely an experimental declaration, even if it introduces breaking changes.
Regarding stable declarations, we can only deprecate them incrementally following the « Warning > Error > Hidden » pattern used by Kotlin itself.

Evolution principles

• New declarations should be introduced in experimental stage for collecting user feedbacks.
• Experimental declarations could be promoted to a stable stage when releasing a new minor or major version by:
  1. removing the corresponding annotation marking it as experimental
  2. updating the version in the SinceKotoolsTypes version annotation.
• Experimental declarations could be updated or removed freely in next minor or major versions.
• Stable declarations should be removed by following the Warning-Error-Hidden pattern used by Kotlin itself. For example, if a declaration was deprecated with a Warning level in the version X.Y, we could:
  • promote its deprecation level to Error in the X.(Y + 1) version
  • promote its deprecation level to Hidden in the X.(Y + 2) version
  • remove it in the X.(Y + 3) or the (X + 1).0 versions.

[LVMVRQUXL]

Updates on the release cycle

For adopting an agile methodology, we want to reduce the amount of changes packed in releases by releasing new versions more frequently than 1 minor version per quarter.
Instead, we will release new versions when ready with a maximum of 10 changes documented in the changelog.

[LVMVRQUXL]

Updates on the release cycle

For adopting an agile methodology, we want to reduce the amount of changes packed in releases by releasing new versions more frequently than 1 minor version per quarter.

Instead, we will release new versions when ready with a maximum of 10 changes documented in the changelog.

We are now back to our regular release plan: 1 minor version per quarter.

[LVMVRQUXL]

Updates on versioning strategy

The Semantic Versioning being a system widely used in open-source projects for indicating what type of changes are included in a new release, we will go back to this release strategy starting from version 4.3.2.
The goal of this change is to improve our communication about what's new in each version.

Updates on declarations lifecycle

For being able to apply the Semantic Versioning strategy, we have to change our declarations evolution principles like so:

• New declarations should be introduced in experimental stage for collecting user feedbacks.
• Experimental declarations could be promoted to a stable stage when releasing a new minor or major version by:
  1. removing the corresponding annotation marking it as experimental
  2. replacing the ExperimentalSinceKotoolsTypes annotation by the SinceKotoolsTypes annotation with an updated version value.
• Experimental declarations could be updated or removed freely in next minor or major versions.
• Stable declarations should be removed by following the Warning-Error-Hidden pattern provided by Kotlin. For example, if a declaration was stabilized in the version X.Y.Z, we should:
  • deprecate it with a Warning level in the version X.(Y + 1).0
  • promote its deprecation level to Error in the version (X + 1).0.0
  • promote its deprecation level to Hidden in the version (X + 2).0.0
  • remove it in the version (X + 3).0.0.

[LVMVRQUXL]

Experimental usages

Like discussed in the issue #77, we shouldn't opt-in at the module level an experimental API: it doesn't communicate the real stability of a declaration to consumers. Instead, we should propagate the experimental annotation or marking the declaration with an Opt-in annotation.

For choosing between propagating an experimental annotation or marking a declaration with an Opt-in annotation:

• if the experimental type is part of our public API, we should propagate the annotation
• if the experimental declaration is an implementation detail, we should:
  • propagate the annotation if it's not in our control
  • opt-in the experimental declaration.

[LVMVRQUXL]

This documentation is now available in Declarations lifecycle.