DOC: incorporate knowledge about maint/ branches into documentation

[yarikoptic]

Your idea

originally triggered by @effigies asking in

• https://github.com/bids-standard/bids-specification/pull/2079#issuecomment-2704978255

and me 🤔 about a lovely maint/ branch, reminiscent of maint/ branch I maintain in DataLad, but never heard about in BIDS, and could not find docs describing on decision making on what to go there:

❯ git grep 'maint\>'
.github/workflows/publish_schema.yml:      - "maint/*"
.github/workflows/publish_schema.yml:            echo "branch=jsr-maint" | tee -a $GITHUB_OUTPUT
.github/workflows/publish_schema.yml:            echo "mode=maint" | tee -a $GITHUB_OUTPUT
.github/workflows/schemacode_ci.yml:      - "maint/*"
.github/workflows/schemacode_ci.yml:      - "maint/*"

So it would be nice if documentation, e.g. likely https://github.com/bids-standard/bids-specification/blob/master/CONTRIBUTING.md and https://github.com/bids-standard/bids-specification/blob/master/Release_Protocol.md would tell us what to do there and when to release from it etc.

FWIW, I would have loved all fixes indeed be done there, and BIDS specification getting regular if not fully automated .patch releases whenever we e.g. fix a typo or alike ;)

More info and graphics to potentially borrow in

• https://github.com/bids-standard/bids-specification/issues/1977

[effigies]

Just to add a related issue in the validator:

• https://github.com/bids-standard/bids-validator/issues/85

Brain dump:

• Schema publication
  • In-document: The schema.json file is bundled into every build (e.g., https://bids-specification.readthedocs.io/en/latest/schema.json) via readthedocs: https://github.com/bids-standard/bids-specification/blob/3b6d2f7c8bd060e9b7efb15ecb93011c500df72c/readthedocs.yml#L30-L32
  • bidsschematools: PyPI release is triggered by schema-* tags.
  • JSR: A jsr-dist branch is maintained that contains the skeleton of https://jsr.io/@bids/schema/1.0.3 (latest version as of this post). On every commit to master, the branch is checked out and some typescript files are regenerated from the schema and metaschema. https://github.com/bids-standard/bids-specification/blob/3b6d2f7c8bd060e9b7efb15ecb93011c500df72c/.github/workflows/publish_schema.yml#L54-L70 If there are any changes to any of these components, then a new version is calculated, a new commit pushed to the branch, and the state of the branch is pushed to https://jsr.io/@bids/schema/versions.
    • A jsr-maint branch is maintained that is only triggered by schema releases on the maint/* branches.
• Release process
  • BIDS releases
    • Bump both BIDS_VERSION and SCHEMA_VERSION. Tag $BIDS_VERSION and schema-$SCHEMA_VERSION.
      • BIDS_VERSION needs to be set manually. SCHEMA_VERSION can be set with bump-my-version from the tools/schemacode directory (see below)
      • Generally follow the release guidelines, just push a schema-$SCHEMA_VERSION tag as well.
      • git push upstream $BIDS_VERSION:maint/$BIDS_VERSION
      • Bump the patch version of BIDS_VERSION and the minor version of SCHEMA_VERSION, mark both -dev, commit and push to master.
  • Schema-only releases
    • Previously done on master, now only done on maint/* branches to ensure that the published schema does not run ahead of BIDS.
    • Bump SCHEMA_VERSION and tag schema-$SCHEMA_VERSION

      uvx bump-my-version bump pre_label --tag
      # Push current branch and tag
      git push upstream $( git rev-parse --abbrev-ref HEAD ) $( git describe )
      # Wait for CI to run
      uvx bump-my-version patch  # or major/minor, as appropriate
      git push
      

    • Merge maint/* into master:

      git checkout -t upstream/master
      git merge -X ours maint/$BIDS_VERSION
      git push
      

[effigies]

One additional note, that didn't make it into those linked issues: Because of an inability to use + versions in @bids/schema, we moved from schema-0.minor.patch+postN to schema-major.minor.patch, where minor is generally to be incremented with a new BIDS release and patch is to be incremented with releases that do not affect the semantics of the BIDS_VERSION, which stays constant.

It is conceivable that the minor or even major version would be incremented on a maint/* branch, if the changes to the schema justified it, but then the master branch would need to bump an additional minor version over the latest maint/* branch.