Deprecation plan for STAC versions <1.0

[duckontheweb]

It seems like it would simplify the code base significantly and make long-term maintenance more manageable if we were able to remove support for pre-1.0 STAC spec versions. However, we want to do this in a way that is transparent for users and allows them to plan for updates to libraries that have PySTAC as a dependency. Since removing support for these pre-1.0 versions represents a breaking change, we will also need to consider how it affects versioning of this library. Do we want to remove support for these versions prior to a PySTAC 1.0 release, or should we release 1.0 with deprecation notices for these versions and remove them in a 2.0 release? In either case, we should have a public plan for handling these deprecations in place by the PySTAC 1.0 release.

The purpose of this issue is to discuss a plan for deprecating and subsequently removing support for these pre-1.0 STAC spec versions.

cc: @lossyrob @gadomski @matthewhanson @jbants

[matthewhanson]

I personally am fine with aggressive deprecation of pre-1.0 versions. Going forward I think it makes sense to have a long support period for 1.0, but don't think support for pre-1.0 catalogs is needed. I'd even go so far as to remove all pre-1.0 support for a final PySTAC 1.0.0 release. Everyone should update their STAC!

[gadomski]

I'd even go so far as to remove all pre-1.0 support for a final PySTAC 1.0.0 release. Everyone should update their STAC!

Will people use PySTAC to update their STAC? If so, we'll have to keep at least rudimentary pre-STAC-1.0 support to help with those conversions. I don't have a sense of how people update their STAC so unsure if this is a real problem for users.

[duckontheweb]

Will people use PySTAC to update their STAC? If so, we'll have to keep at least rudimentary pre-STAC-1.0 support to help with those conversions. I don't have a sense of how people update their STAC so unsure if this is a real problem for users.

I think that given the existing migration functionality in PySTAC we have probably positioned ourselves this way. It's going to be hard to know how much people are actually using this, but I think we probably need to assume that they are. Given that, it seems like we should have a stable release that includes support for STAC >=0.8 (including 1.0) with tools for migrating.

Maybe the best course of action is to add deprecation notices for pre-1.0 STAC versions in PySTAC 1.0 and to remove those in a PySTAC 2.0 release. We could plan on doing that PySTAC 2.0 release within 2-3 months to give people some time to migrate their catalogs.

[lossyrob]

While I think dropping pre-1.0 support is eventually what we want, I don't think it should happening too quickly. The logic that deals with earlier versions is mostly in the migrate, identify and validation logic. This logic shouldn't really change for pre-1.0 STAC, and now that STAC is at 1.0, shouldn't even change for 1.0 STAC. Having pre-1.0 migration and validation is going to be useful to users who take some time to upgrade their STACs, and there's many reasons why someone might not be able to upgrade in a 2-3 month time frame. That said, PySTAC 1.0 should work with migrating to STAC 1.0, and we're not planning on new major releases of STAC anytime soon, so someone could just use this next version of PySTAC for their migrations even if it's dropped in a later version.

Remember too that stac-validator depends on the validation logic in PySTAC, and works with older versions of STAC. If we drop pre-1.0 support from PySTAC, it will affect this downstream library and likely others, removing the migration and validation features for them. I think we'd want to have a broader buy-in in the STAC community to totally drop support of pre-1.0 catalogs; that's something that we'll get to, but I don't know that we should try to rush, and providing tooling to help folks who are a bit later to the upgrade is valuable and worth the maintenance burden IMO.

Longer term deprecation plans aside, my opinion is that we want pre-1.0 support in this next PySTAC 1.0 release to support users doing upgrades.

[scottyhq]

I was trying to look for version migration docs, am I just overlooking them? I think it would be very useful to update https://github.com/stac-utils/stac-examples to 1.0.0 and document how that is done.

[lossyrob]

@scottyhq good call, we should have a migration section in the docs.

In the meantime - if you read in and then write out a STAC with the 1.0.0rc1 release, it will be upgraded to STAC 1.0. You should be able to do this all at the root catalog. Here is an example of a script that migrates one file at a time, which we use to upgrade the test data.

[duckontheweb]

Longer term deprecation plans aside, my opinion is that we want pre-1.0 support in this next PySTAC 1.0 release to support users doing upgrades.

That all sounds good to me. Let's plan on releasing 1.0.0 with support for STAC >=0.8. As we get close to a 2.0.0 release we can revisit this and add in some deprecation notices for STAC <1.0.0.

[m-mohr]

fwiw, people can alternatively use stac-migrate which supports upgrading to the latest STAC and extensions via CLI. You need nodejs, but it will allow migrating from 0.6 and later for another year or two at least.

[gadomski]

As discussed in a stac-utils working group meeting, it's probably not necessary to keep pre-v1.0 migration capabilities for PySTAC v2. If folks have pre-v1.0 STAC, they can use PySTAC v1.x to get to STAC v1.0.0, then use PySTAC v2 as they will.