Skip to content

Document the contract versioning rule: increase on any change of result, independently of applications #96

Closed

Description

@PierreRaybaut

Problem

#95 (closing #94) kept the operation contracts at version 1 in Sigima 1.4 and wrote in doc/contributing/guidelines.rst that "version 1 of the contracts is settled by the first stable release of an application recording them (DataLab 1.4): until then, contract versions are not increased". This ties the versioning of Sigima to the releases of an application, which is wrong: Sigima is a reference of its own.

The actual rule is:

  • the version of a contract is increased whenever a change of a computation function changes the result it returns, in the change itself, whatever the releases of DataLab or of any other application;
  • keeping version 1 between 1.3.0 and 1.4.0 was a one-off exception (contracts just published, not used yet), which does not apply to later changes.

The rule is also poorly documented: only in the contributing guidelines; nothing in the user guide, nothing in the instructions for AI agents (whose "adding a function" example even omits operation_id).

Proposal

  • Guidelines: state the rule, its exceptions (previously refused inputs now accepted; changes without effect on the result; changes entirely covered by a versioned rule of the execution context, whose version is increased instead) — inputs previously accepted and now refused do require an increase —, a checklist for changing a computation function, and the historical note on 1.4.
  • New user guide page "Operation contracts and versions".
  • Release note for 1.4 on the one-off exception.
  • .github/copilot-instructions.md: operation contracts section, corrected example, checklist for modifying a computation function.
  • Docstrings of sigima.proc.contracts and computation_function(contract_version=...).
  • French translations.

Activity

  1. PierreRaybaut commented on Oct 25, 2026

    @PierreRaybaut
    ContributorAuthor

    Done in #97 (merged into develop).

  2. added this to the v1.4.0 milestone on Oct 27, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions