From 78d4cd6690d4146bd841d0567e07c6ac38462fc6 Mon Sep 17 00:00:00 2001 From: Sherwin-14 Date: Fri, 12 Jul 2024 22:27:23 +0530 Subject: [PATCH 01/14] Added documentation page for backwards compatability This PR is aimed at solving the issue no `closes #471` --- CHANGELOG.md | 3 ++ docs/user_guide/backwards-compatibility.md | 44 ++++++++++++++++++++++ 2 files changed, 47 insertions(+) create mode 100644 docs/user_guide/backwards-compatibility.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 882538ea..e7148781 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -26,6 +26,9 @@ - Add support for Python 3.12 ([#457](https://github.com/nsidc/earthaccess/issues/457)) ([**@chuckwondo**](https://github.com/chuckwondo),[**@mfisher87**](https://github.com/mfisher87)) +- Added documentation for the backwards compatibility + ([#471](https://github.com/nsidc/earthaccess/issues/471)) + ([**@Sherwin-14**](https://github.com/Sherwin-14),[**@mfisher87**](https://github.com/mfisher87)) ### Removed diff --git a/docs/user_guide/backwards-compatibility.md b/docs/user_guide/backwards-compatibility.md new file mode 100644 index 00000000..40880df5 --- /dev/null +++ b/docs/user_guide/backwards-compatibility.md @@ -0,0 +1,44 @@ +# 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. + +## Our versioning scheme + +We use [SemVer](https://semver.org/) 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: + + 1. There are 3 version parts: MAJOR.MINOR.PATCH (e.g. 1.2.3 is major version 1, minor release 2, patch release 3). + 2. When the major version changes, anything can break! Always visit this documentation before doing a major upgrade. + 3. When the minor version changes, new features should be available, but nothing should break. Visit the documentation to learn about new features. + 4. When the patch version changes, only bugfixes should be included. Visit the CHANGELOG to learn more about the fixes. + +## Our commitments + +### Versioning + +We will follow SemVer. All version changes will consider [this](https://example.com/our-public-api) to be the public API documentation for the purposes of deciding whether a change is breaking or non-breaking. + +### Release Communication + +1. We will announce releases on the following channels: ___ +2. Release announcements will include a prominent notification of breaking changes, including a link to migration guide. + +### CHANGELOG + +1. We will update the CHANGELOG for every release +2. The CHANGELOG will include prominent notification of breaking changes, including a link to migration guide. + +### Fixing Backwards Incompatible Changes + +1. We will plan to fix any backwards incompatible changes in non-major releases. + +2. We cannot guarantee developers will be available to complete this work alongside other priorities. + +3. Our maintenance team will always welcome outside contributions towards this goal. + +4. Please use an issue to communicate about this work. + +## Migration guides + +Under Development 🚧 + +This section will contain migration guides for future releases. Check back soon for updates! From 234c9faa23c6e96feb9db024a8f13ca399e41e1b Mon Sep 17 00:00:00 2001 From: Sherwin Varghese <141290943+Sherwin-14@users.noreply.github.com> Date: Mon, 15 Jul 2024 11:36:26 +0530 Subject: [PATCH 02/14] Used full form for Semver Co-authored-by: Matt Fisher --- docs/user_guide/backwards-compatibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user_guide/backwards-compatibility.md b/docs/user_guide/backwards-compatibility.md index 40880df5..4bb18312 100644 --- a/docs/user_guide/backwards-compatibility.md +++ b/docs/user_guide/backwards-compatibility.md @@ -4,7 +4,7 @@ We care deeply about minimizing negative impacts of changes to earthaccess, but ## Our versioning scheme -We use [SemVer](https://semver.org/) 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: +We use [Semantic Versioning (SemVer)](https://semver.org/) to tell users what to expect when upgrading. We recommend following the link to learn more, but here are the important ways this affects you: 1. There are 3 version parts: MAJOR.MINOR.PATCH (e.g. 1.2.3 is major version 1, minor release 2, patch release 3). 2. When the major version changes, anything can break! Always visit this documentation before doing a major upgrade. From 5146b012a450629f2d2d195d71988b0849e5f476 Mon Sep 17 00:00:00 2001 From: Sherwin Varghese <141290943+Sherwin-14@users.noreply.github.com> Date: Mon, 15 Jul 2024 11:37:22 +0530 Subject: [PATCH 03/14] Corrected some semantics Co-authored-by: Matt Fisher --- docs/user_guide/backwards-compatibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user_guide/backwards-compatibility.md b/docs/user_guide/backwards-compatibility.md index 4bb18312..c5771e24 100644 --- a/docs/user_guide/backwards-compatibility.md +++ b/docs/user_guide/backwards-compatibility.md @@ -6,7 +6,7 @@ We care deeply about minimizing negative impacts of changes to earthaccess, but We use [Semantic Versioning (SemVer)](https://semver.org/) to tell users what to expect when upgrading. We recommend following the link to learn more, but here are the important ways this affects you: - 1. There are 3 version parts: MAJOR.MINOR.PATCH (e.g. 1.2.3 is major version 1, minor release 2, patch release 3). + 1. There are 3 version parts: `MAJOR.MINOR.PATCH` (e.g. `1.2.3` is major version `1`, minor release `2`, patch release `3`). 2. When the major version changes, anything can break! Always visit this documentation before doing a major upgrade. 3. When the minor version changes, new features should be available, but nothing should break. Visit the documentation to learn about new features. 4. When the patch version changes, only bugfixes should be included. Visit the CHANGELOG to learn more about the fixes. From 8814b4ee3525bb51aa4f538432701bf3659ca468 Mon Sep 17 00:00:00 2001 From: Sherwin Varghese <141290943+Sherwin-14@users.noreply.github.com> Date: Mon, 15 Jul 2024 11:38:00 +0530 Subject: [PATCH 04/14] Minor grammatical change (before --> when) Co-authored-by: Matt Fisher --- docs/user_guide/backwards-compatibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user_guide/backwards-compatibility.md b/docs/user_guide/backwards-compatibility.md index c5771e24..bfc6770a 100644 --- a/docs/user_guide/backwards-compatibility.md +++ b/docs/user_guide/backwards-compatibility.md @@ -7,7 +7,7 @@ We care deeply about minimizing negative impacts of changes to earthaccess, but We use [Semantic Versioning (SemVer)](https://semver.org/) to tell users what to expect when upgrading. We recommend following the link to learn more, but here are the important ways this affects you: 1. There are 3 version parts: `MAJOR.MINOR.PATCH` (e.g. `1.2.3` is major version `1`, minor release `2`, patch release `3`). - 2. When the major version changes, anything can break! Always visit this documentation before doing a major upgrade. + 2. When the major version changes, anything can break! Always visit this documentation when doing a major upgrade. 3. When the minor version changes, new features should be available, but nothing should break. Visit the documentation to learn about new features. 4. When the patch version changes, only bugfixes should be included. Visit the CHANGELOG to learn more about the fixes. From a3a5d0c2ece73a6757844c0f100780d52b1306d7 Mon Sep 17 00:00:00 2001 From: Sherwin Varghese <141290943+Sherwin-14@users.noreply.github.com> Date: Mon, 15 Jul 2024 11:38:29 +0530 Subject: [PATCH 05/14] Added a link to open bug reporting Co-authored-by: Matt Fisher --- docs/user_guide/backwards-compatibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user_guide/backwards-compatibility.md b/docs/user_guide/backwards-compatibility.md index bfc6770a..6b9e5600 100644 --- a/docs/user_guide/backwards-compatibility.md +++ b/docs/user_guide/backwards-compatibility.md @@ -8,7 +8,7 @@ We use [Semantic Versioning (SemVer)](https://semver.org/) to tell users what to 1. There are 3 version parts: `MAJOR.MINOR.PATCH` (e.g. `1.2.3` is major version `1`, minor release `2`, patch release `3`). 2. When the major version changes, anything can break! Always visit this documentation when doing a major upgrade. - 3. When the minor version changes, new features should be available, but nothing should break. Visit the documentation to learn about new features. + 3. When the minor version changes, new features should be available, but nothing should break. Visit the documentation to learn about new features. If you discover any breaking changes, please [open a bug report](https://github.com/nsidc/earthaccess/issues/new)! 4. When the patch version changes, only bugfixes should be included. Visit the CHANGELOG to learn more about the fixes. ## Our commitments From fe2a223dbe05bbc5656d71363388f688498e338e Mon Sep 17 00:00:00 2001 From: Sherwin Varghese <141290943+Sherwin-14@users.noreply.github.com> Date: Mon, 15 Jul 2024 11:44:06 +0530 Subject: [PATCH 06/14] Added Link to Common Change Log Co-authored-by: Matt Fisher --- docs/user_guide/backwards-compatibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user_guide/backwards-compatibility.md b/docs/user_guide/backwards-compatibility.md index 6b9e5600..f857db65 100644 --- a/docs/user_guide/backwards-compatibility.md +++ b/docs/user_guide/backwards-compatibility.md @@ -24,7 +24,7 @@ We will follow SemVer. All version changes will consider [this](https://example. ### CHANGELOG -1. We will update the CHANGELOG for every release +1. We will update the CHANGELOG for every release following [Common Changelog](https://common-changelog.org/) style. 2. The CHANGELOG will include prominent notification of breaking changes, including a link to migration guide. ### Fixing Backwards Incompatible Changes From 0082b923486296986daba318d510baa9ad64de5b Mon Sep 17 00:00:00 2001 From: Sherwin Varghese <141290943+Sherwin-14@users.noreply.github.com> Date: Mon, 15 Jul 2024 11:45:05 +0530 Subject: [PATCH 07/14] Updated the file with a minor change for migration guide Co-authored-by: Matt Fisher --- docs/user_guide/backwards-compatibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user_guide/backwards-compatibility.md b/docs/user_guide/backwards-compatibility.md index f857db65..cb8ab78e 100644 --- a/docs/user_guide/backwards-compatibility.md +++ b/docs/user_guide/backwards-compatibility.md @@ -20,7 +20,7 @@ We will follow SemVer. All version changes will consider [this](https://example. ### Release Communication 1. We will announce releases on the following channels: ___ -2. Release announcements will include a prominent notification of breaking changes, including a link to migration guide. +2. Release announcements will include a prominent notification of breaking changes, including migration instructions. ### CHANGELOG From 322e7eb0087b46a5fa3d5fb8b0818f5714b3bd0a Mon Sep 17 00:00:00 2001 From: Sherwin Varghese <141290943+Sherwin-14@users.noreply.github.com> Date: Mon, 15 Jul 2024 11:46:07 +0530 Subject: [PATCH 08/14] Updated with a minor change for fixing backwards incompatible changes Co-authored-by: Matt Fisher --- docs/user_guide/backwards-compatibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user_guide/backwards-compatibility.md b/docs/user_guide/backwards-compatibility.md index cb8ab78e..7a727bb2 100644 --- a/docs/user_guide/backwards-compatibility.md +++ b/docs/user_guide/backwards-compatibility.md @@ -29,7 +29,7 @@ We will follow SemVer. All version changes will consider [this](https://example. ### Fixing Backwards Incompatible Changes -1. We will plan to fix any backwards incompatible changes in non-major releases. +1. We will plan to fix any backwards incompatible changes in non-major releases _or_ re-release with a major version bump. 2. We cannot guarantee developers will be available to complete this work alongside other priorities. From 19ad9770ee9fce9ab4d014adfc4e3ada74117c58 Mon Sep 17 00:00:00 2001 From: Sherwin Varghese <141290943+Sherwin-14@users.noreply.github.com> Date: Mon, 15 Jul 2024 11:51:31 +0530 Subject: [PATCH 09/14] Added a change for not guaranteeing timeline Co-authored-by: Matt Fisher --- docs/user_guide/backwards-compatibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user_guide/backwards-compatibility.md b/docs/user_guide/backwards-compatibility.md index 7a727bb2..9e7bac5b 100644 --- a/docs/user_guide/backwards-compatibility.md +++ b/docs/user_guide/backwards-compatibility.md @@ -31,7 +31,7 @@ We will follow SemVer. All version changes will consider [this](https://example. 1. We will plan to fix any backwards incompatible changes in non-major releases _or_ re-release with a major version bump. -2. We cannot guarantee developers will be available to complete this work alongside other priorities. +2. We cannot guarantee a timeline under which maintainers will be able to complete this work alongside their other priorities. 3. Our maintenance team will always welcome outside contributions towards this goal. From b70bf4e47c271dd10d2eea408eecb25ab2471bda Mon Sep 17 00:00:00 2001 From: Sherwin Varghese <141290943+Sherwin-14@users.noreply.github.com> Date: Mon, 15 Jul 2024 11:52:20 +0530 Subject: [PATCH 10/14] Added Link for reporting Github Issue Co-authored-by: Matt Fisher --- docs/user_guide/backwards-compatibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user_guide/backwards-compatibility.md b/docs/user_guide/backwards-compatibility.md index 9e7bac5b..b2f19eb5 100644 --- a/docs/user_guide/backwards-compatibility.md +++ b/docs/user_guide/backwards-compatibility.md @@ -35,7 +35,7 @@ We will follow SemVer. All version changes will consider [this](https://example. 3. Our maintenance team will always welcome outside contributions towards this goal. -4. Please use an issue to communicate about this work. +4. Please use a [GitHub Issue](https://github.com/nsidc/earthaccess/issues) to communicate about this work. ## Migration guides From 63bd4a297d6e03260931bf861806fd41ccfc1de8 Mon Sep 17 00:00:00 2001 From: Sherwin-14 Date: Sun, 15 Sep 2024 22:58:43 +0530 Subject: [PATCH 11/14] Completed tasks as discussed --- docs/user_guide/backwards-compatibility.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/user_guide/backwards-compatibility.md b/docs/user_guide/backwards-compatibility.md index b2f19eb5..9ba8f345 100644 --- a/docs/user_guide/backwards-compatibility.md +++ b/docs/user_guide/backwards-compatibility.md @@ -15,7 +15,7 @@ We use [Semantic Versioning (SemVer)](https://semver.org/) to tell users what to ### Versioning -We will follow SemVer. All version changes will consider [this](https://example.com/our-public-api) to be the public API documentation for the purposes of deciding whether a change is breaking or non-breaking. +We will follow SemVer. All version changes will consider [this](https://example.com/our-public-api) to be the public [API](user-reference/api/api) documentation for the purposes of deciding whether a change is breaking or non-breaking. ### Release Communication @@ -37,6 +37,10 @@ We will follow SemVer. All version changes will consider [this](https://example. 4. Please use a [GitHub Issue](https://github.com/nsidc/earthaccess/issues) to communicate about this work. +## Our Python and dependency support policy + +Our project follows the SPEC0 dependency deprecation policy, which outlines the guidelines for deprecating and removing dependencies from our codebase. + ## Migration guides Under Development 🚧 From b7d0937833303389d8d70c8a62db4919410d6db1 Mon Sep 17 00:00:00 2001 From: Sherwin Varghese <141290943+Sherwin-14@users.noreply.github.com> Date: Mon, 16 Sep 2024 10:33:14 +0530 Subject: [PATCH 12/14] Update docs/user_guide/backwards-compatibility.md with SPEC0 link Co-authored-by: Matt Fisher --- docs/user_guide/backwards-compatibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user_guide/backwards-compatibility.md b/docs/user_guide/backwards-compatibility.md index 9ba8f345..b70333ac 100644 --- a/docs/user_guide/backwards-compatibility.md +++ b/docs/user_guide/backwards-compatibility.md @@ -39,7 +39,7 @@ We will follow SemVer. All version changes will consider [this](https://example. ## Our Python and dependency support policy -Our project follows the SPEC0 dependency deprecation policy, which outlines the guidelines for deprecating and removing dependencies from our codebase. +Our project follows the [SPEC0](https://scientific-python.org/specs/spec-0000/) dependency version deprecation policy, which outlines the guidelines for upgrading dependencies of _earthaccess_. ## Migration guides From c839136c8f81c4a1a4bdf38bbda177651e32a29f Mon Sep 17 00:00:00 2001 From: Sherwin-14 Date: Tue, 17 Sep 2024 19:27:25 +0530 Subject: [PATCH 13/14] Added navigation link to mkdocs.yml --- mkdocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/mkdocs.yml b/mkdocs.yml index ab48481f..8ab9ad6f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -72,6 +72,7 @@ nav: - "Authentication": "user_guide/authenticate.md" - "Search": "user_guide/search.md" - "Access": "user_guide/access.md" + - "Backwards Compatibility": "user_guide/backwards-compatibility.md" - HOW-TO: - "Authenticate with Earthdata Login": "howto/authenticate.md" - "Search NASA datasets using filters": "howto/search-collections.md" From 088a075b0b679b03036b3410ec15271cb9896714 Mon Sep 17 00:00:00 2001 From: Sherwin-14 Date: Tue, 17 Sep 2024 22:25:49 +0530 Subject: [PATCH 14/14] Added the announcement channel --- docs/user_guide/backwards-compatibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user_guide/backwards-compatibility.md b/docs/user_guide/backwards-compatibility.md index b70333ac..d11636dd 100644 --- a/docs/user_guide/backwards-compatibility.md +++ b/docs/user_guide/backwards-compatibility.md @@ -19,7 +19,7 @@ We will follow SemVer. All version changes will consider [this](https://example. ### Release Communication -1. We will announce releases on the following channels: ___ +1. We will announce releases on the following channel: [Github Releases](https://github.com/nsidc/earthaccess/releases) 2. Release announcements will include a prominent notification of breaking changes, including migration instructions. ### CHANGELOG