lock versions of STAC core and Features API

[cholmes]

We should have released versions of STAC API mark certain versions of underlying specs as dependencies, and be clear on what version they depend on up front.

We should update all the links to be sure they track the actual version. This will likely involve find & replace for each release, unless we figure out some way to automatically do it.

• Update submodule to point at STAC core 1.0.0-beta.2
• Add note about properly checking out submodules
• Update stac-spec links to be relative
• Make clear the features API dependency
• Add what updates are needed for a 'release' (update submodule, stac links)

[m-mohr]

Agreed for Features API, but couldn't/shouldn't the API be able to operate on multiple STAC versions? Also, if we fix it to STAC, we also need to re-release once a new STAC version is out. Maybe just specify a version range (e.g. >= 0.9.0 and < 2.0)?

[cholmes]

Ah, that's fair.

I was mostly thinking about making sure the link references to the STAC spec used the 'tags', instead of just master (which may change and possibly break the links).

Should we say 0.9.0 and above for STAC API beta.1? I guess your < 2.0 is just signaling that STAC API doesn't guarantee to work with a breaking change?

[cholmes]

Actually I'm realizing that the 'stac-spec @ 568a048' external folder thing in the repo is maybe meant to help with links not breaking? I was starting to do full URL references to STAC spec. But it looks like I can do relative ones to that folder, which we can 'upgrade' at our leisure?

Seems like we should probably 'set' it to 1.0.0-beta.1 of STAC spec for now? And then I can update the links to refer to it relatively. I have no idea how to work with those. But if that route makes sense I can dig in - I'm guessing that's why we had it in there in the first place?

[m-mohr]

Yeah, makes sense to set it to beta.2 and make relative links.

Should we say 0.9.0 and above for STAC API beta.1? I guess your < 2.0 is just signaling that STAC API doesn't guarantee to work with a breaking change?

Yes, that was my intention.

[cholmes]

Ok, I'll change them to relative links.

Though do we need to explicitly tell people to get the sub-modules? I just have empty directories, and reading https://stackoverflow.com/questions/3796927/how-to-git-clone-including-submodules it looks like that is the norm. Should we remind people how to check it out to be sure to get the right stac-spec so the relative links work?

[m-mohr]

Hmm... yeah submodules are tricky. I guess most people read it online, but a note somewhere doesn't hurt, right?
I'm not even sure I like the submodules approach, but I have no better solution yet I could propose.

[m-mohr]

The PR has been merged. Feel free to close once you've done your changes, @cholmes .

[cholmes]

Yeah, I don't have any better approach than submodules. It seems to fit the bill, they just seem a little trickier to work with.

Added checkboxes of the things I need to do.

[matthewhanson]

git subtrees is a better alternative to submodules in some cases. It's more transparent, the subtree is included when you clone. But in this case I think submodules are probably better because we want to reference a fixed version of stac-spec. subtrees are good if you want to be able to commit back upstream from the subtree package, but we don't need to do that here.