Ctrl+K

Model Promotion Policy

Model Promotion Policy#

This document defines the minimum bar a model must meet before it can be promoted from experimental to stable. The goal is to make promotion a deterministic, reviewable decision rather than a subjective one.

Stability Tiers#

DeepTab ships models at two tiers:

Tier

Meaning

Experimental

API may change without a deprecation cycle. No stability guarantees. Flagged in docs and docstrings.

Stable

Public API is frozen under semantic versioning. Breaking changes require a deprecation notice ≥ one minor release before removal.

A model enters the codebase as experimental. A maintainer promotes it to stable by opening a dedicated promotion PR once every criterion below is met.

Promotion Requirements#

1. Public API#

The model’s public constructor signature must be consistent with other stable estimators in deeptab/models/. Parameter names must follow existing conventions (e.g. n_layers, d_model, dropout). __init__ must accept a config object from deeptab/configs/ with all config fields reflected as constructor kwargs.

2. Documentation#

A model page must exist under docs/api/models/ and include:

  • A one-paragraph description of the architecture.

  • A When to use section — what problem or data type this model is suited for.

  • A Limitations section — known failure modes, dataset-size requirements, or computational constraints.

  • A full parameter table generated from the config docstring.

All public methods must have docstrings that pass make doctest.

3. End-to-end Example#

At least one runnable example must exist in examples/ or docs/examples/ that demonstrates loading data, constructing the model, fitting, and predicting. The example must run to completion without error against the current main branch.

4. Save / Load Support#

If save/load is part of the stable core contract for the task type, the model must be saveable and reloadable via the standard DeepTab mechanism, with a round-trip test confirming identical predictions before and after reload.

5. Tests#

A behavioral test must exist (in a dedicated file or in tests/test_base.py) covering:

  • Fit on a small synthetic dataset.

  • Predict returning an array of the expected shape and dtype.

  • Config serialization round-trip.

All tests must pass in CI (just test).

6. No Open Critical Bugs#

No open GitHub issues labelled bug for the model may describe a failure in a core workflow (fit, predict, save/load). Known limitations that are not bugs must be documented in the model’s Limitations section.

7. Registry#

A config class must exist in deeptab/configs/ and be exported from deeptab/configs/__init__.py. The model must be exported from deeptab/models/__init__.py and listed in deeptab/utils/config_mapper.py.

Promotion PR#

Open a PR titled feat(<model-name>): promote to stable. The PR must:

  1. Remove any .. experimental:: admonition from the model’s doc page.

  2. Remove any ExperimentalWarning raised in __init__ or fit.

  3. Remove the experimental badge from the API reference entry.

  4. Add the model to the changelog under ### Promoted to Stable.

Approval requires at least one maintainer review beyond the author. Use the promotion checklist in the PR template to track each requirement.

Demotion#

Demotion back to experimental is only warranted if a critical correctness bug is found that cannot be fixed without a breaking API change. In that case:

  1. Open an issue labelled regression and breaking.

  2. Add an ExperimentalWarning in the next patch release pointing to the issue.

  3. Fix the problem and re-promote via the standard requirements above.

Demotion is not itself a breaking change, but it must be documented prominently in the release notes.

Contents