Document our commitments and processes for backwards compatibility

[mfisher87]

Related: #573

Probably won't be reliably responsive here for at least a day, but wanted to get these thoughts down while I had the opportunity.

I think we need a place where people can look to understand how to manage their code with respect to earthaccess backwards compatibility. This will also be an opportunity to stealthily help our userbase skill up (perhaps "stealth" is not the best choice of word -- what I mean is teach people without them needing to seek out learning the thing we're teaching), for example, by teaching terminology and providing usable examples of how to specify an environment that will avoid a specific breaking change. The following is a brainstorm of what I think this could look like. There's surely more discussion to be had regarding upper bounds. (TODO: Link to relevant issue)

@betolink @asteiker I think this is really important to have on a checklist to complete before 1.0. Perhaps we should create a milestone?

---

Our commitments to backwards compatibility

We care deeply about minimizing negative impacts of changes to earthaccess, but we also care deeply about making earthaccess the most valuable it can be to our users. These are sometimes in conflict, and this documentation helps us make decisions that balance these needs in a way that's best for our users.

This document is not set in stone and should be updated as we learn about the effectiveness of these practices.

Our versioning scheme

We use SemVer (or EffVer?) to tell you what to expect when upgrading. We recommend following the link to learn more, but here are the important ways this affects you:

• There are 3 version parts: MAJOR.MINOR.PATCH (e.g. 1.2.3 is major version 1, minor release 2, patch release 3).
• When the major version changes, anything can break! Always visit this documentation before doing a major upgrade.
• When the minor version changes, new features should be available, but nothing should break. Visit the documentation to learn about new features.
• When the patch version changes, only bugfixes should be included. Visit the CHANGELOG to learn more about the fixes.

Pre-1.0

List of pre-1.0 releases with major breaking changes

• v0.Y.Z (migration guide
• etc.

Our commitments

• We will follow SemVer / EffVer. All version changes will consider this to be the public API documentation for the purposes of deciding whether a change is breaking or non-breaking.
• Releases with breaking changes will include a migration guide in the documentation.
• We will announce releases on the following channels: ___
  • Release announcements will include a prominent notification of breaking changes, including a link to migration guide.
• We will update the CHANGELOG for every release
  • The CHANGELOG will include prominent notification of breaking changes, including a link to migration guide.
• We will plan to fix any backwards incompatible changes in non-major releases.
  • We cannot guarantee developers will be available to complete this work alongside other priorities. Our maintenance team will always welcome outside contributions towards this goal. Please use an issue to communicate about this work.
• ...

Pre-1.0 commitments

Pre-1.0, breaking changes are allowed in minor versions under SemVer.

• Migration guides will be added to this page, in the "List of pre-1.0 releases with major breaking changes" section.
• We will make breaking changes in minor releases.
• ...

Best practices we recommend

Use an environment specification file

• We recommend an environment specification file because it clearly records what version of earthaccess your code was built to use, and makes it easier to recreate a similar environment.
• We recommend using the PEP440 compatible release specification style to clearly and succinctly represent your application's constraints.
• We recommend allowing only patch upgrades to occur without manual review, e.g.: earthaccess ~=0.8.2.
  • When we reach v1.0.0, this recommendation will change to: allow only minor and major upgrades to occur without manual review, e.g.: earthaccess ~=1.0.

Other best practice

... use a lockfile? etc.

---

Migration guides

This is a listing page of all earthaccess migration guides for releases with breaking changes.

...

---

Example migration guide: v2.0.0

vX.Y.Z contains breaking changes! If you're not ready to upgrade to this release, please use the following configuration:

(We can have a tabbed code window here with examples for conda, poetry, pip, pixi, etc.)

name: my-environment
channels:
  - conda-forge
dependencies:
  - "earthaccess ~=1.0"

Please see our backwards compatibility best practices for more on why we recommend this style of specification and how to use it.

Migration steps

...

[Sherwin-14]

@mfisher87 Hey Matt, Is the issue description complete(I mean to say are these the only points to be kept in consideration when building a doc for this)? If yes then do you have any specific opinions on this one?

[mfisher87]

I believe nobody has weighed in on this idea except me, but perhaps there was some discussion in Slack I forgot about :) I think the best next step is to identify which items here are concrete and don't require new decisions, and document them; for example: we already use semantic versioning, we are pre-1.0 and so make breaking changes more, and we care deeply about avoiding negative impacts on our userbase. We could open a PR which documents and explains those things that we know are already true, we can merge that uncontroversially, then we can create a 2nd PR for the proposed policies, and that can act as a stimulus for further discussion and decisions. What do you think?

[mfisher87]

Oh, and an opinion I forgot about: I think this should be a new document in the user guide. This is not aimed at contributors, it's a "covenant" with our users.

[Sherwin-14]

This seems like a great path! We can lock down what is important for us in this phase and document them, and then overhaul the doc as we go on. I found something which might be of our interest in here.

Numpy Backwards compatibility and deprecation policy - https://numpy.org/neps/nep-0023-backwards-compatibility.html

[mfisher87]

Since numpy and many other libraries we expect our users to use have adopted SPEC0, I think that's where we should be. IMO we can go forward with documenting that as our policy, as we have discussed it before, and it seemed uncontroversial. Let's make sure we get consensus before we merge though.

Are we "big" enough to get earthaccess added to the "endorsed by" list?

[Sherwin-14]

I guess we should start? Any considerations like sections that we can/have to omit for this draft from the issue description?

[mfisher87]

For now, I think let's skip the best practices section. I think we should include a "migration guides" section which says something like "under construction" until we're ready to start adding them.

[Sherwin-14]

Hey Matt, Can you assign me this one?

[mfisher87]

Thanks for taking this on! 🚀