How to contribute to MLM specification or stac-model

September 8, 2026 ยท View on GitHub

Project setup

  1. If you don't have uv installed run:

    make setup

    This installs uv as a standalone application.
    For more details, see also the uv documentation.

  2. Initialize project dependencies with uv and install pre-commit hooks:

    make install-dev
make pre-commit-install

    This will install project dependencies into the currently active environment. If you would like to use uv's default behavior of managing a project-scoped environment, use uv commands directly to install dependencies. uv sync will install dependencies and dev dependencies in .venv and update the uv.lock.

PR submission

Before submitting your code please do the following steps:

  1. Add any changes you want

  2. Add tests for the new changes

  3. Edit documentation if you have changed something significant

    You're then ready to run and test your contributions.

  4. Run linting checks:

    make lint-all

  5. Run tests (including your new ones) with

    make test

  6. Upload your changes to your fork, then make a PR from there to the main repo:

    git checkout -b your-branch
git add .
git commit -m ":tada: Initial commit"
git remote add origin https://github.com/your-fork/mlm-extension.git
git push -u origin your-branch

Building and releasing

Warning

There are multiple types of releases for this repository:

  1. Release for MLM specification (usually, this should include one for stac-model as well to support it)
  2. Release for stac-model only

Building a new version of MLM specification

  • Checkout to the main branch by making sure the CI passed all previous tests.
  • Bump the version with bump-my-version bump --verbose <version-level>.
    • Consider using --dry-run beforehand to inspect the changes.
    • The <version-level> should be one of major, minor, or patch.
      Alternatively, the version can be set explicitly with --new-version <version> patch.
      For more details, refer to the Semantic Versions standard;
  • Make a commit to GitHub and push the corresponding auto-generated v{MAJOR}.{MINOR}.{PATCH} tag.
  • Validate that the CI validated everything once again.
  • Create a GitHub release with the created tag.

Warning

  • Ensure the "Set as the latest release" option is selected :heavy_check_mark:.
  • Ensure the diff ranges from the previous MLM version, and not an intermediate stac-model release.

Note

Publishing the release tag automatically deploys the strict v{MAJOR}.{MINOR}.{PATCH}/schema.json to GitHub Pages. It also generates v{MAJOR}.{MINOR}/schema.json and v{MAJOR}/schema.json "redirects" which copy the release for matching semantic versions. These version copies replace the explicit version check of the MLM extension URI in stac_extensions to a more lenient pattern matching of corresponding versions. This allows referencing the schemas with permissive ignore of certain changes only related to package maintenance without actual impact on the mlm: field definitions and the corresponding JSON schema. See generate_schema_redirects.py and publish.yaml for details.

Building a new version of stac-model

  • Apply any relevant changes and CHANGELOG.md entries in a PR that modifies stac-model.
  • Bump the version with bump-my-version bump --verbose <version-level> --config-file stac-model.bump.toml.
    • You can pass the new version explicitly, or a rule such as major, minor, or patch.
      For more details, refer to the Semantic Versions standard;
  • Once CI validation succeeded, merge the corresponding PR branch.
  • Checkout to main branch that contains the freshly created merge commit.
  • Push the tag stac-model-v{MAJOR}.{MINOR}.{PATCH}. The CI should auto-publish it to PyPI.
  • Create a GitHub release (if not automatically drafted by the CI).

Warning

  • Ensure the "Set as the latest release" option is deselected :x:.
  • Ensure the diff ranges from the previous release of stac-model, not an intermediate MLM release.

Other help

You can contribute by spreading a word about this library. It would also be a huge contribution to write a short article on how you are using this project. You can also share how the ML Model extension does or does not serve your needs with us in the GitHub Discussions or raise Issues for bugs.