search

bids-standard / bids-specification

Brain Imaging Data Structure (BIDS) Specification
https://bids-specification.readthedocs.io/
Creative Commons Attribution 4.0 International
277 stars 162 forks source link

Specification/schema development policy and branching #1977

Open effigies opened 1 day ago

effigies commented 1 day ago

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:

---
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"

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 https://github.com/bids-standard/bids-validator/issues/85, where I expect the discussion to focus more around the mechanics of keeping validator branches synchronized to schema releases.

effigies commented 13 hours ago

I've created maint/1.10.0: https://github.com/bids-standard/bids-specification/compare/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: https://github.com/bids-standard/bids-specification/compare/maint/1.10.0...master

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