API Lifecycle

To ensure a set of stable APIs, we introduced an API lifecycle. This will allow us to introduce/incubate new features while keeping the stable one up and running.

Principle to work for

If we extend our existing functionalities while following the open-closed principle, there should not be any breaking changes visible to our users.

But as you all know, it is not that simple. Ensuring backward compatibilities is directly impacting maintainability in the following ways:

  • code we do not delete needs to be maintained (unittests and doc included)

  • legacy APIs may include switch cases in new APIs

  • legacy APIs may include dependencies to classes or modules we do not need

Different use-cases

Use-case

User expectations

Size of the complexity

Refinement of a functionality

stable APIs

medium

Refactoring activities of a functionality

stable APIs

medium

Incubation of a new functionality

unstable APIs

big

API States

State

Description

stable

The API is stable and will not change in the future

incubation

The API is not stable and may change in the future

deprecated

The API is not recommended for use and may be removed in the future

removed

The API is removed and no longer available

Approach

Contribution of a new module

  1. In src/pykiso/lib/incubation are two folders, one dedicated for the incubation of auxiliaries and the other for connectors.

  2. Depending on the type of module you want to contribute (How to create a connector or How to create an auxiliary), create a module in the right folder.

  3. Do not forget the unittests (same location of all unittests).

  4. Do not forget to add your module to the documentation. Also add a warning section to inform the user that this module is in incubation phase.

  5. Do not forget to add an usage example for your module.

Refactoring of an existing module

  1. In src/pykiso/lib/incubation are two folders, one dedicated for the incubation of auxiliaries and the other for connectors.

  2. Copy the module to refactor to the right folder.

  3. Update/Refactor the APIs. Breaking the Api is fine in Incubation.

  4. In the old location, if possible, inherit from it and replace the content of the legacy APIs. There should be no breaking changes, this step is to support backward compatibility.

  5. In the documentation, extend the already existing .rst file with a warning specifying which APIs are in incubation / refactored and which one will be deprecated and removed in the next major release.

  6. Extend the unittests to test the refactored APIs. Old tests should not be touched, they ensure the backward compatibility.

  7. Do not forget the warning.

  8. Users can access the new functionalities with from ebplugins.incubation.emb_aux the APIs with breaking changes.

  9. Update the examples to use the new API.

Deprecation of an existing module

  1. In the documentation, add a deprecation warning to the APIs.

  2. In case of a module, add a deprecation warning to the module.

Versioning

Like for any other changes, we will be using conventional commits.

The versioning will be done according to the semantic versioning.

Version

Changes to expect

patch

no breaking changes, no new incubation feature, no deprecation

minor

no breaking changes in stable code, breaking changes for incubation features, new incubation feature, deprecation of an existing feature, move of an incubation feature to stable

major

breaking changes, new incubation feature, deletion of deprecated feature

ref: https://www.sebastianpfischer.com/index.php/2023/02/21/how-to-deal-with-breaking-changes-python/