Skip to content

Contributing 🌟

Pull Requests are the primary method of contributing to the spec itself, and everyone is welcome to submit changes. Suggestions for changes to the core will be taken with higher priority if a clear implementation of ML-STAC API has been built that can highlight the problem.

We consider everyone using the specification to catalog their data to be a 'contributor', as ML-STAC is really about the end result of more interoperable data, not just creating a spec for the sake of it.

So if you want to help then the best thing you can do is make new catalogs or build software that uses the spec. And please do give us feedback. The best place to do so is on our GitHub disscussion. If you are interested in helping but aren't sure where to, then see the mlstac-demo repo for ideas on how to use the ML-STAC specification to create a real-world dataset.

Development Process 💻

The Machine Learning SpatioTemporal Asset Catalogs (ML-STAC) API specification is under active development.

The main branch is a place of active development, where a new change in one part of the spec might not yet be fully updated everywhere else. Releases are tagged. The team uses the ml-stac issue tracker to identify and track all that will be done for a release. Once all the major issues are resolved the core team makes sure everything is consistent across the spec and examples.

Submitting Pull Requests 📝

Any proposed changes to the specification should be done as pull requests. Please make these requests against the main branch.

Creating a Pull Request will show our PR template, which includes checkbox reminders for a number of things, including adding an entry the CHANGELOG and making the PR against the main branch.

All pull requests should submit clean markdown, which is checked by the continuous integration system. All pull requests that modify or create JSON schema files or examples should use JSON formatter to keep files consistent across the repo. All pull requests that modify or create Python code should use black and isort to keep files consistent across the repo.

All pull requests additionally require a review of two ML-STAC core team members. Releases are cut from main and require 3 approvals.

Release Process 🚀

To release a new version of the STAC spec the following list of tasks must be done.

  • Update Issue Tracker: Each release has a milestone in the github issue tracker, and before a release is done all open issues that are filed against it should be reviewed. All issues do not need to be completed, but the core release team should all review the issues to make sure that the critical ones for the release have been addressed. Issues that aren't seen as essential should be moved to future releases, so that there are no open issues against the milestone.
  • Check dependencies: ML-STAC relies on STAC - TrainingDML-AI, ML AOI extensions and STAC Core specifications at its core, will likely rely on additional Features API extensions such as the OGC Training Data Markup Language for AI. We aim to always reference the latest version of these, so before releasing we should check to make sure we are on the latest stable versions, and upgrade if it makes sense.
  • Agreement from core team: The core ML-STAC team should meet (on video or on github discussion) and decided that the release is ready. This should include review of the issues, as well as looking at the spec holistically, to make sure the new changes keep with a coherent whole.
  • Final Spec Read Through: There should be a final read through of the core specification to make sure it makes sense and there are no typos, errors, etc.
  • Update the Changelog: The changelog should be reviewed to make sure it includes all major improvements in the release. And anything in 'unreleased' section should move to the version of the spec to be released.
  • Release on Github: The final step to create the release is to add a new 'release' on https://github.com/IPL-UV/ml-stac/releases. This should use a tag like the others, with a 'v' prefix and then the release number, like v0.5.2. The changelog should be copied over to be the release notes, and then also include a link to the full milestone of everything closed in the issue tracker.
  • Promote the release: A blog post and tweet should be composed and sent out, and then inform those in the github discussion channel to post / promote it.

Release Candidates 📦

Before any release that has major changes (made as a judgement call by the core contributors) there should be a 'release candidate' to ensure the wider community of implementors can try it out and catch any errors before a full release. It is only through actual implementations that we can be sure the new spec version is good, so this step is essential if there are major changes.

Governance 🏛️

The ML-STAC API spec follows the same governance as the core STAC spec.

Back to top