Skip to content

MIxS Editing Workflows and Good Practices

Please try to follow this document. First read the policies document.

Terms

Requesting and creating a new term

Requesting and implementing a term update

Requesting and implementing a term deprecation

Checklists, extensions, and combinations

Define what they are

Requesting and creating a new checklist or extension

Updating an existing checklist or extension

Releases

The GSC creates releases using semantic versioning (major.minor.patch).

Version strings

MIxS carries two version numbers, managed differently. Both use bare X.Y.Z values (no v); the v is a git tag label only.

  • Python package version (pyproject.toml): derived from the git tag by poetry-dynamic-versioning. It is not edited by hand; pyproject.toml holds a 0.0.0 placeholder on main, and the real value is stamped from the tag at build time.
  • Schema version (src/mixs/schema/mixs.yaml version:): this is content. It flows into the generated OWL (pav:version), which EBI OLS reads, and into the JSON Schema and datamodel. It is bumped by hand as part of a release (see below), following the same pattern as biolink-model.

Cutting a release

  1. Bump the schema version by editing the version: field near the top of src/mixs/schema/mixs.yaml to the new release number (bare X.Y.Z). Commit it to main via the normal PR process. Pushing this to main triggers the "Regenerate and verify generated artifacts" workflow, which regenerates the OWL and other project/ artifacts so they carry the new version.
  2. Run the "Create Release PR" GitHub Action (manual dispatch) with the same version. It bumps CITATION.cff, .zenodo.json, and release/README.md, generates the schema diff, and opens a release/vX.Y.Z PR. It does not touch pyproject.toml (dynamic) or mixs.yaml (already bumped in step 1).
  3. Add the schema-diff summaries to the release branch (see below).
  4. Review and merge the release PR.
  5. Create a GitHub Release with tag vX.Y.Z and generate release notes.

The structured diff in step 2 is produced by the reusable diff-releases tool; see SCHEMA_DIFFING.md.

Adding the schema-diff summaries and publishing them

The structured diff is complete but large. Before the release PR is reviewed, add readable summaries to the release branch and put them on the docs site:

  1. Check out the release/vX.Y.Z branch.
  2. The release action already wrote the diff into a per-release folder, assets/diff_results/<old>_to_<new>/ (for example v6.2.0_to_v6.3.0/). Work in that folder. (The docs build publishes summaries only from these per-release folders.)
  3. Run the mixs-diff-summary skill on the structured diff, for example /mixs-diff-summary assets/diff_results/<old>_to_<new>/schema_comparison_results.yaml. It writes agent_summary.md next to the structured diff.
  4. Commit both agent_summary.md (the readable summary) and tool_summary.md (the counts) in that folder.
  5. Add the two pages to the site nav. In mkdocs.yml, under the Version changes group, add two lines for this release: ```yaml
    • to : version-changes/to.md
    • to (counts): version-changes/to-counts.md `` Thegendocbuild step copies the two summaries out ofassets/diff_results/to/intodocs/version-changes/` automatically, so no other change is needed.

This runs on the branch, done by a maintainer or an agent, not in CI. It needs no API keys, and everything is reviewed like any other change before merge.

Reviewing and publishing

  • A TWG member other than the PR author reviews the version bumps and the schema diff summary. The pre-merge checklist is in the PR body.
  • After merge, create the GitHub Release with tag vX.Y.Z and publish.

Keeping generated artifacts current

The committed artifacts under project/, src/mixs/datamodel/, and contrib/ are generated from the schema. The "Regenerate and verify generated artifacts" workflow keeps them in sync. On a push to main that changes the schema or its build inputs, it regenerates everything and commits the refreshed artifacts. On a pull request it regenerates and fails if the committed artifacts are stale.

The check uses project/jsonschema/mixs.schema.json as its signal, because that file regenerates deterministically. The OWL (project/owl/mixs.owl.ttl) is not byte-reproducible: RDF/Turtle serialization reorders triples and blank nodes on every run, so it is regenerated and committed but not compared by diff. Do not hand-edit generated artifacts.

LinkML Updates

Documentation

Autogenerated documentation is created with every PR Sujay's fork allows you to preview what will be regenerated. Important for when the documentation technology changes.

Content copied over:

  • All change requests to the GSC should be captured in an issue.
  • Issues should be descriptive and provide clear requests and changes. Issue templates are available and should be used when possible.

  • One change should be proposed per issue. If multiple issues are related, you can leverage a GitHub super issue to connect related items.

  • All branches should be tied to issues and the branch name should relate to the issue it's tied to.

  • This can be accomplished easily using the GitHub "create a branch" tool when viewing the issue on the webpage.

  • All pushes, pull requests, and changes should be related to a single issue, and issues should be a single change per issue.

  • Issues and their associated pull requests should be small and targeted. One change per issue and pull request.

  • All branches and pull requests should be tied to an issue.

  • When making a pull request, contributions can continue to be made and built, but within scope of the related issue.

  • Making a draft pull request can be done to confirm changes are being done correctly

  • Provide a reviewer for pull requests.

  • Pull requests must be reviewed by a member of the GSC Technical Working Group
  • A Pull request requires someone other than the person that created the pull request

  • Include issue author as a pull request reviewer

  • Once a pull request is started, all further discussion, review, and changes, happen in the pull request (rather than the issue).

  • ?? Using conversations within PRs (TODO: add links to GH documentation)

  • When a pull request is merged, the associated branch should be deleted and issue closed.

  • The GSC will create releases (ADD Details, # of PRs? on a schedule?)

  • The GSC will use semantic versioning for releases: 3 digits (major, minor, patch)
  • Create a project for the release or other large change set

  • A change log for a release will be generated from all the pull requests that are part of the repository since the last release.

  • All issues that pertain to a release should be part of a project for that release.

  • Contributions should NOT be made in a fork.

  • If external parties make a fork, it should be tied to an issue. Forks will only be merged back in following the above criteria for branches and small changes.
  • It is expected that external parties will discuss with the Technical Working Group before making changes on a scale that require a fork (e.g. a new checklist or extension).
  • The preference is to avoid forks and will be reviewed on a case by case basis.

  • Whenever a fork is created, a Technical Working Group member will reach out to the creator

  • Add require a description to the suggested new thing to the requirements

  • New extensions or checklists should be tracked using GitHub Projects

  • Add require a description to the suggested new thing to the requirements

  • New extensions or checklists should be tracked using GitHub Projects