Skip to content

Deprecation policy

This document defines how tucoopy (Python) handles API changes.

Goal

  • Avoid drift and repeated refactors.
  • Provide predictability for users and for the documentation.

Versions 0.x

The project is in an alpha phase (0.x):

  • Breaking API changes may still happen.
  • Still, we try to deprecate before removing when it does not add too much cost.
  1. Mark as deprecated
  2. Document in the changelog.
  3. Update docs (reference page, examples).
  4. Emit a warning
  5. Use DeprecationWarning (or a specific exception) only when it makes sense.
  6. Remove
  7. Prefer removing in the next "minor" (e.g. 0.2.0), or at most in +2 releases.

"Ghost files" and duplicates

Empty files (or files with # delete) should not remain:

  • Prefer actually removing them.
  • If removal is not possible (environment constraints), keep a module that:
  • fails on import with an explicit error, and
  • explains the replacement (new path / new source-of-truth layer).

JSON contract compatibility

Compatibility should be maintained at the JSON contract level (tucoopy.io.schema), not via module shims/aliases.