Skip to content

Document when Sigima contract versions change #433

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
PierreRaybaut merged 1 commit into from
Oct 25, 2026
Merged

Document when Sigima contract versions change #433

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 26 additions & 2 deletions .github/copilot-instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -179,7 +179,14 @@ python scripts/run_with_env.py python -m sphinx build doc build/doc -b html -D l
**Example: Implementing a New Processing Feature**

```python
# 1. Implement computation in Sigima (sigima/proc/signal/processing.py)
# 1. Implement computation in Sigima (sigima/proc/signal/processing.py), with its
# operation contract (see "Adding a New Signal Processing Feature" for the
# contract versioning rule)
@computation_function(
operation_id="sigima.signal.my_processing_func",
contract_version=1,
qualification=ReplayQualification(contract_version=1, comparison=EXACT),
)
def my_processing_func(src: SignalObj, param: MyParam) -> SignalObj:
"""My processing function."""
dst = src.copy()
Expand Down Expand Up @@ -546,15 +553,32 @@ menu_title = "Processing" # Not translatable!

**Complete workflow**:

1. **Implement computation in Sigima** (`sigima/proc/signal/processing.py`):
1. **Implement computation in Sigima** (`sigima/proc/signal/processing.py`), with its
operation contract (identifier, version, replay qualification):
```python
@computation_function(
operation_id="sigima.signal.my_feature",
contract_version=1,
qualification=ReplayQualification(contract_version=1, comparison=EXACT),
)
def my_feature(src: SignalObj, param: MyParam | None = None) -> SignalObj:
"""My feature."""
dst = src.copy()
# ... computation ...
return dst
```

**Contract versioning rule (mandatory)**: when a change of an existing Sigima computation
function changes the result it returns (values, outputs, defaults, parameters, inputs now
refused), increase its `contract_version` (and its qualification) in Sigima in the same change,
**whatever the releases of DataLab**: Sigima is a reference of its own. Only previously refused
inputs now accepted, changes without effect on the result, or changes covered by a versioned
rule of the execution context (image ROI convention, X alignment) do not require it. The 1.4
exception (contracts kept at version 1) was one-off and does not apply anymore. Then update the
DataLab provenance tests that check a contract version
(`datalab/tests/features/common/provenance_*_test.py`). Full rules: Sigima
`doc/contributing/guidelines.rst` and `doc/user_guide/contracts.rst`.

2. **Export from Sigima** (`sigima/proc/signal/__init__.py`):
```python
from sigima.proc.signal.processing import my_feature # Import
Expand Down
11 changes: 11 additions & 0 deletions doc/features/common/provenance.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -239,6 +239,17 @@ references. The signal and image phase spectra are identified but not qualified.
Unknown operations, versions, codecs or policies produce an explicit refusal:
the reader never downloads code to guess their meaning.

Sigima increases the version of an operation contract whenever a change of the
computation changes its result, whatever the version of DataLab. Activities
recorded with an earlier version of the contract are then refused explicitly
(*unsupported contract*) instead of being replayed with a different result, and
their processing cannot be applied again as recorded: compute the result again
to record it with the current version. The same applies to the versioned rules
of the execution context, such as the selection of image pixels by regions of
interest. See `Operation contracts and versions
<https://sigima.readthedocs.io/en/latest/user_guide/contracts.html>`_ in the
Sigima documentation.

Scientific fingerprints cover numerical data, types, coordinates and units;
ROI are checked separately. Titles, display settings and other metadata are not
automatically covered. Only declared dependencies such as global options,
Expand Down
3 changes: 3 additions & 0 deletions doc/locale/fr/LC_MESSAGES/features/common/provenance.po
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -228,6 +228,9 @@ msgstr "Les plugins, macros, scripts et clients de l'API distante sont enregistr
msgid "A replay needs a local operation contract qualified for the recorded version, decodable parameters, applicable context, available input data and valid output references. The signal and image phase spectra are identified but not qualified. Unknown operations, versions, codecs or policies produce an explicit refusal: the reader never downloads code to guess their meaning."
msgstr "Un rejeu nécessite un contrat d'opération local qualifié pour la version enregistrée, des paramètres décodables, un contexte applicable, des données d'entrée disponibles et des références de sortie valides. Les spectres de phase signal et image sont identifiés mais non qualifiés. Une opération, une version, un codec ou une politique inconnus produisent un refus explicite : le lecteur ne télécharge jamais de code pour en deviner le sens."

msgid "Sigima increases the version of an operation contract whenever a change of the computation changes its result, whatever the version of DataLab. Activities recorded with an earlier version of the contract are then refused explicitly (*unsupported contract*) instead of being replayed with a different result, and their processing cannot be applied again as recorded: compute the result again to record it with the current version. The same applies to the versioned rules of the execution context, such as the selection of image pixels by regions of interest. See `Operation contracts and versions <https://sigima.readthedocs.io/en/latest/user_guide/contracts.html>`_ in the Sigima documentation."
msgstr "Sigima augmente la version d'un contrat d'opération dès qu'une modification du calcul change son résultat, quelle que soit la version de DataLab. Les activités enregistrées avec une version antérieure du contrat sont alors refusées explicitement (*contrat non pris en charge*) au lieu d'être rejouées avec un résultat différent, et leur traitement ne peut pas être réappliqué tel qu'enregistré : recalculez le résultat pour l'enregistrer avec la version actuelle. Il en va de même pour les règles versionnées du contexte d'exécution, comme la sélection des pixels d'une image par les régions d'intérêt. Voir `Contrats d'opération et versions <https://sigima.readthedocs.io/en/latest/user_guide/contracts.html>`_ dans la documentation de Sigima."

msgid "Scientific fingerprints cover numerical data, types, coordinates and units; ROI are checked separately. Titles, display settings and other metadata are not automatically covered. Only declared dependencies such as global options, X alignment or metadata read by the computation are reproduced. For example, changing fit parameters needed by ``evaluate_fit`` can refuse replay even if the signal values are unchanged."
msgstr "Les empreintes scientifiques couvrent les données numériques, les types, les coordonnées et les unités ; les ROI sont contrôlées séparément. Les titres, les paramètres d'affichage et les autres métadonnées ne sont pas automatiquement couverts. Seules les dépendances déclarées, telles que les options globales, l'alignement en X ou les métadonnées lues par le calcul, sont reproduites. Par exemple, modifier les paramètres d'ajustement nécessaires à ``evaluate_fit`` peut entraîner un refus de rejeu même si les valeurs du signal sont inchangées."

Expand Down
Loading