[RFC] Versioning scheme for stac-utils Python projects

[gadomski]

Summary

All Python packages in the stac-utils organization will have a consistent versioning scheme based on semantic versioning, with the caveat that it is impossible to strictly adhere to that system. These projects will maintain a hand-curated, meaningful CHANGELOG that provides useful information about the changes contained in each release.

List of projects

This is a list of projects that have explicitly stated that they are following the practices in this RFC:

• None (update as needed)

Motivation

Semantic Versioning (SemVer) is a widely-used versioning scheme that is based on three numbers, MAJOR, MINOR, and PATCH, each separated by a . (e.g. MAJOR.MINOR.PATCH). SemVer is intended as a communication mechanism that allows software developers to inform their users about breaking, non-breaking, and bugfix changes to software.

While SemVer is nice in theory, in practice it is common for a "non-breaking" release of a dependency to break one's code. The excellent Semantic Versioning Will Not Save You outlines some of the pitfalls of relying on SemVer. However, as the article states:

This article is not about discouraging maintainers from using SemVer for their projects if they like it. There’s nothing wrong about encoding the intent of a release into the version number as a service to its users.

This RFC describes the intent of MAJOR, MINOR, and PATCH releases for Python projects in stac-utils, in the hopes that users can cautiously rely on those release numbers in their downstream projects. While many projects are implicitly implementing SemVer now, it is considered best practice to explicitly state a project's versioning scheme. This RFC can be a single source of truth for the versioning scheme for all projects that choose to implement it.

Guide-level explanation

The Semantic Versioning Specification will be used. It is not copied here in full, but some key points are:

• MAJOR, MINOR, and PATCH are all non-negative integers without any leading zeros.
• PATCH changes indicate a backwards compatible bug fix.
• MINOR changes indicate backwards compatible functionality in the public API, deprecation of part of a public API, and substantial new functionality in private code.
• MAJOR changes indicate backwards incompatible changes to the public API.
• Version 1.0.0 defines the public API
• Initial development releases starting with "0.y.z" can treat changes in "y" as a major release, and "z" as a minor release. "0.0.z" releases are always major changes (taken from https://doc.rust-lang.org/cargo/reference/semver.html).

Projects are encouraged to stay in initial development (MAJOR == 0) until they are willing to commit to a public API. In this way, we can engender some measure of trust in the stability of MAJOR >= 1 stac-utils Python projects. At the same time, projects in initial development are encouraged to create a public roadmap to a 1.0.0 release.

Downstream users of stac-utils Python projects are well advised by Hynek Schlawack's article (linked above):

that’s all SemVer is: a TL;DR of the changelog.

When new versions are released, users are encouraged to inspect the CHANGELOG for information about what has changed, and how that might effect their systems. Software maintainers will keep an up-to-date CHANGELOG with links to relevant pull requests and issues, describing all changes and potential side effects.

Unresolved questions

• How should projects indicate that they are following the guidelines in this RFC? A note in their README?
• If accepted, should this RFC be published somewhere else?
• Should we have any sort of official review/audit mechanism for new releases of stac-utils Python packages?

Future possibilities

This author has written up some strategies around using Github Actions to protect against breaking changes in Python projects, with help from @TomAugspurger. We could try to collect a variety of notebooks, software projects, etc that use our core packages (pystac and pystac-client come to mind) and create a "compatability matrix" for new releases through automated testing of these downstreams.

[TomAugspurger]

Thanks for writing this up!

Projects are encouraged to stay in initial development (MAJOR == 0) until they are willing to commit to a public API. In this way, we can engender some measure of trust in the stability of MAJOR >= 1 stac-utils Python projects.

I'd also encourage that projects write down a set of goals (even in a GitHub issue) that they consider blockers for 1.0. Just to nudge them along :)

How should projects indicate that they are following the guidelines in this RFC? A note in their README?

Either a README or docs, whichever is more appropriate for that project IMO.

If accepted, should this RFC be published somewhere else?

Good idea. I think a stac-utils/governance or stac-utils/policies repository would make a good home.

Should we have any sort of official review/audit mechanism for new releases of stac-utils Python packages?

IMO, no. I think that would introduce too much friction in the release process. I think just trusting the maintainers is OK.

[gadomski]

Cheers, thanks. Updated the RFC to include encouragement to create a 1.0.0 roadmap.