Specification/schema development policy and branching

[effigies]

The BIDS specification, schema and validator lifecycles are currently mixed. The schema is updated linearly with main, and there is no method to maintain a branch of the schema that fixes issues with the schema for the stable release without also including new features in the main branch.

As the validator is now heavily reliant on the schema, there is no difference to the validator between an update that fixes a bug in the schema and one that introduces a feature, which could potentially be changed or reverted before the next release of BIDS.

Here I propose a parallel branching strategy for the specification and the validator.

Legend:

• main: bids-specification:main
• maint/1.10.0: bids-specification:maint/1.10.0
• validator-stable: bids-validator:stable (or bids-validator:maint/1.15.x)
• validator-main: bids-validator:main

---
config:
  gitGraph:
    parallelCommits: false
---
gitGraph TB:
  branch validator-stable order: 2
  commit id: "v1.15.0.devN"
  checkout main
  commit tag: "v1.10.0" id: "schema-0.11.3"
  branch maint/1.10.0 order: 1
  checkout validator-stable
  merge main tag: "v1.15.0"
  branch validator-main order: 3
  checkout main
  commit id: "schema-0.11.4.dev1"
  checkout validator-main
  merge main id: "v1.15.1.dev1"
  checkout main
  commit id: "schema-0.11.4.dev2"
  checkout validator-main
  merge main id: "v1.15.1.dev2"
  checkout main
  checkout maint/1.10.0
  commit id: "schema-0.11.3.post1"
  checkout validator-stable
  merge maint/1.10.0 tag: "v1.15.1"
  checkout main
  merge maint/1.10.0 id: "schema-0.11.4.dev3"
  checkout validator-main
  merge main id: "v1.15.1.dev3"
  checkout main
  commit id: "schema-0.11.4.dev4"
  checkout validator-main
  merge main id: "v1.15.1.dev4"
  checkout main
  commit id: "schema-0.11.4.dev5"
  checkout validator-main
  merge main id: "v1.15.1.dev5"
  checkout maint/1.10.0
  commit id: "schema-0.11.3.post2" tag: "v1.10.0.post1"
  checkout validator-stable
  merge maint/1.10.0 tag: "v1.15.2"
  checkout main
  merge maint/1.10.0 id: "schema-0.11.4.dev6"

Loading

By using .postN releases for fixes to the schema and .devN releases for new changes, the stable validator could follow the latest .post and the development version could follow the latest .dev.

I also include a v1.10.0.post1 tag, which could be used for schema fixes that have rendering consequences, or things like fixing typos in the spec.

Note that the "merges" between the specification and validator branches are not actual git merges. They would be the validator updating pins to versions of the schema pushed to https://jsr.io/@bids/schema/versions.

---

This post is motivated by validation considerations, but has implications for how we operate on the specification. Therefore I am posting this here, as well as bids-standard/bids-validator#85, where I expect the discussion to focus more around the mechanics of keeping validator branches synchronized to schema releases.

[effigies]

I've created maint/1.10.0: v1.10.0...maint/1.10.0

I believe this contains the semantically neutral differences that have been merged since the release of v1.10.0. Please let me know if you disagree. You can also see the changes against master, which I didn't include: maint/1.10.0...master

I will start working on the tooling to handle the schema publication from the maintenance branch.

[effigies]

We have now had a schema-0.11.3.post1 release off of the maint/1.10.0 branch., which pushed to https://pypi.org/project/bidsschematools/0.11.3.post1/#history and https://jsr.io/@bids/schema@0.11.3+1

I believe the infrastructure needed in this repository is complete. The validator will now need a maintenance branch to track the stable releases.

[Remi-Gau]

@effigies

I added a branch proctection for the 'maint' branches: I will let you edit it further.

https://github.com/bids-standard/bids-specification/settings/branches

[effigies]

Thanks @Remi-Gau. I updated the branch definition (maint/*), and I set it to require one reviewer. Their job will be to ensure that the changes are semantically neutral in the spec (as opposed to the schema, which can be brought more into line with the spec), which should be sufficient for maint/* branches.