DOC: incorporate knowledge about maint/ branches into documentation

[yarikoptic]

Your idea

originally triggered by @effigies asking in

• feat(schema): Add selectors to file rules #2079 (comment)

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

• Specification/schema development policy and branching #1977

[effigies]

Just to add a related issue in the validator:

• BIDS support policy and branching bids-validator#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:
    

    bids-specification/readthedocs.yml

    Lines 30 to 32 in 3b6d2f7

    	pre_build:
    	- bst -v export --output src/schema.json
    	- tools/no-bad-schema-paths.sh src/schema.json # README.md might need fixing

  • 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.
    

    bids-specification/.github/workflows/publish_schema.yml

    Lines 54 to 70 in 3b6d2f7

    	- name: Checkout ${{ steps.branch.outputs.branch }}
    	run: |
    	git checkout -t origin/$JSR_BRANCH
    	env:
    	JSR_BRANCH: ${{ steps.branch.outputs.branch }}
    	- name: Regenerate schema
    	run: bst export > schema.json
    	- name: Regenerate context types
    	run: |
    	jq .meta.context schema.json \
    	| npx quicktype --src-lang schema --lang ts -t Context --just-types \
    	> context.ts
    	- name: Regenerate metaschema types
    	run: |
    	# Name the file schema so the type will be named Schema
    	bst export-metaschema > /tmp/schema.json
    	npx --package=json-schema-to-typescript json2ts --unknownAny /tmp/schema.json > metaschema.ts

    
    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.