fix(provenance): capture defaults to off (#1568)

`provenance.capture` shipped defaulting to True, so upgrading to 2.3.4 would have changed the DDL of every Entry table declared afterwards. That is a deployment's decision, not a library default.

It also makes the pair consistent: `jobs.add_job_metadata` already defaults to False for the same reason, and both add a hidden column at declaration.

The platform turns capture on per project through the usual channels -- DJ_PROVENANCE_CAPTURE, the config file, or the secrets directory. Nothing else changes: a table declared with capture on still records on insert, and deploy.add_prov_column still retrofits one declared without it.

Author: dimitri-yatsenko

src/datajoint/deploy.py

@@ -190,10 +190,10 @@ def add_prov_column(target: "TargetType", dry_run: bool = True) -> dict:
     """
     Add the hidden ``_prov`` attribute to Entry (``dj.Manual``) tables that lack it.
 
-    Capture defaults on, so tables declared from 2.3.4 onward already carry the
-    slot.  Two populations do not: tables declared before 2.3.4, and tables
-    declared while ``config.provenance.capture`` was off.  Inserts into those
-    record nothing, silently, and this brings them in line.
+    Capture defaults off, so a table carries the slot only if it was declared
+    while ``config.provenance.capture`` was on.  Every other table -- declared
+    before 2.3.4, or before the deployment enabled capture -- records nothing on
+    insert, silently, and this brings it in line.
 
     It belongs here rather than in :mod:`datajoint.migrate` because it is not a
     one-shot correction of legacy state.  It is idempotent — a table that already

src/datajoint/settings.py

@@ -323,9 +323,11 @@ class ProvenanceSettings(BaseSettings):
     )
 
     capture: bool = Field(
-        default=True,
+        default=False,
         description="Add the hidden `_prov` attribute to Entry (dj.Manual) tables at declaration "
-        "and fill it on insert. Tables declared while this is False never receive the column; "
+        "and fill it on insert. Off by default, matching jobs.add_job_metadata: enabling it changes "
+        "the DDL of every Entry table declared afterwards, which is a deployment's decision rather "
+        "than a library default. Tables declared while this is False never receive the column; "
         "use datajoint.deploy.add_prov_column to add it to an existing table.",
     )
     source: dict[str, Any] = Field(

tests/unit/test_provenance.py

@@ -120,9 +120,14 @@ def test_payload_survives_unserializable_key_values(config):
     assert rendered["context"]["key"]["who"] == "12345678-1234-5678-1234-567812345678"
 
 
-def test_settings_defaults_to_capturing():
-    """A slot nobody can rely on is a slot nobody codes against."""
-    assert Config().provenance.capture is True
+def test_settings_default_to_not_capturing():
+    """Off by default, like `jobs.add_job_metadata`.
+
+    Capture changes the DDL of every Entry table declared afterwards. A library
+    default that does that would make an upgrade to 2.3.4 alter what a schema
+    declares, so the deployment turns it on.
+    """
+    assert Config().provenance.capture is False
     assert Config().provenance.source == {}