From 78d4cd6690d4146bd841d0567e07c6ac38462fc6 Mon Sep 17 00:00:00 2001 From: Sherwin-14 Date: Fri, 12 Jul 2024 22:27:23 +0530 Subject: [PATCH 01/19] 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/19] 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/19] 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/19] 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/19] 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/19] 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/19] 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/19] 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/19] 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/19] 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/19] 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/19] 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/19] 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/19] 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 From d13111812f55cedf803521311f5cb9c7eb8f341e Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Tue, 17 Sep 2024 12:20:42 -0600 Subject: [PATCH 15/19] Quote the pip install specification --- docs/contributing/development.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/development.md b/docs/contributing/development.md index 52e4b676..497b5391 100644 --- a/docs/contributing/development.md +++ b/docs/contributing/development.md @@ -48,7 +48,7 @@ source .venv/bin/activate Install _earthaccess_ in editable mode with optional development dependencies: ```bash -pip install --editable .[dev,test,docs] +pip install --editable ".[dev,test,docs]" ``` ??? note "For conda users" From 3fbc0f3546c3b1dceb01dc01319b7b1e38cce0d3 Mon Sep 17 00:00:00 2001 From: Sherwin-14 Date: Fri, 20 Sep 2024 20:28:07 +0530 Subject: [PATCH 16/19] Added PR examples to Pull Request Template --- .github/pull_request_template.md | 4 ++-- CHANGELOG.md | 7 +++++++ 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 95911c4f..c6771991 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -26,7 +26,7 @@ created the PR as a non-draft, don't worry, you can still change it to a draft u before getting started. - [ ] Ensure an issue exists representing the problem being solved in this PR. - [ ] Populate a descriptive title. For example, instead of "Updated README.md", use a - title such as "Add testing details to the contributor section of the README". + title such as "Add testing details to the contributor section of the README".[Click on this to see an example PR](https://github.com/nsidc/earthaccess/pull/763#event-14296896566) - [ ] Populate the body of the pull request with: - A clear description of the change you are proposing. - Links to any issues resolved by this PR with text in the PR description, for @@ -34,7 +34,7 @@ created the PR as a non-draft, don't worry, you can still change it to a draft u [GitHub docs - Linking a pull request to an issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue). - [ ] Update `CHANGELOG.md` with details about your change in a section titled `## Unreleased`. If such a section does not exist, please create one. Follow - [Common Changelog](https://common-changelog.org/) for your additions. + [Common Changelog](https://common-changelog.org/) for your additions.[Click on this to see an example PR](https://github.com/nsidc/earthaccess/pull/763#event-14296896566) - [ ] Update the documentation and/or the `README.md` with details of changes to the earthaccess interface, if any. Consider new environment variables, function names, decorators, etc. diff --git a/CHANGELOG.md b/CHANGELOG.md index 849fa384..1cab9c40 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -26,6 +26,13 @@ [**@mfisher87**](https://github.com/mfisher87), [**@betolink**](https://github.com/betolink)) +- Added example PR links to pull request template + ([#756](https://github.com/nsidc/earthaccess/issues/756)) + [**@Sherwin-14**](https://github.com/betolink), + [**@mfisher87**](https://github.com/mfisher87) + + + ### Fixed - Removed Broken Link "Introduction to NASA earthaccess" From 3b026a5acd1e1ea9eff0933aa04a2c74f6b75c63 Mon Sep 17 00:00:00 2001 From: Sherwin Varghese <141290943+Sherwin-14@users.noreply.github.com> Date: Fri, 20 Sep 2024 21:36:07 +0530 Subject: [PATCH 17/19] Update .github/pull_request_template.md with proper link Co-authored-by: Matt Fisher --- .github/pull_request_template.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index c6771991..033d3562 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -26,7 +26,8 @@ created the PR as a non-draft, don't worry, you can still change it to a draft u before getting started. - [ ] Ensure an issue exists representing the problem being solved in this PR. - [ ] Populate a descriptive title. For example, instead of "Updated README.md", use a - title such as "Add testing details to the contributor section of the README".[Click on this to see an example PR](https://github.com/nsidc/earthaccess/pull/763#event-14296896566) + title such as "Add testing details to the contributor section of the README". + Example PRs: [#763](https://github.com/nsidc/earthaccess/pull/763) - [ ] Populate the body of the pull request with: - A clear description of the change you are proposing. - Links to any issues resolved by this PR with text in the PR description, for From 26eb63f3659c3e10665d8c9c7ce93ab095e9e1fb Mon Sep 17 00:00:00 2001 From: Sherwin Varghese <141290943+Sherwin-14@users.noreply.github.com> Date: Fri, 20 Sep 2024 21:36:23 +0530 Subject: [PATCH 18/19] Update .github/pull_request_template.md with proper link Co-authored-by: Matt Fisher --- .github/pull_request_template.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 033d3562..8af03cce 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -35,7 +35,8 @@ created the PR as a non-draft, don't worry, you can still change it to a draft u [GitHub docs - Linking a pull request to an issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue). - [ ] Update `CHANGELOG.md` with details about your change in a section titled `## Unreleased`. If such a section does not exist, please create one. Follow - [Common Changelog](https://common-changelog.org/) for your additions.[Click on this to see an example PR](https://github.com/nsidc/earthaccess/pull/763#event-14296896566) + [Common Changelog](https://common-changelog.org/) for your additions. + Example PRs: [#763](https://github.com/nsidc/earthaccess/pull/763) - [ ] Update the documentation and/or the `README.md` with details of changes to the earthaccess interface, if any. Consider new environment variables, function names, decorators, etc. From 2939f80bbd767a4916bc66d33f5f138f5cd15d88 Mon Sep 17 00:00:00 2001 From: Chuck Daniels Date: Fri, 20 Sep 2024 13:52:07 -0400 Subject: [PATCH 19/19] Allow maintainers to run integration tests on PR from a fork (#818) --- .github/actions/install-pkg/action.yml | 3 +- .github/workflows/integration-test.yml | 50 +++++++++++++++++++++++--- .github/workflows/test.yml | 3 +- .gitignore | 1 + docs/contributing/development.md | 23 ++++++------ environment.yml | 4 +++ noxfile.py | 4 +-- 7 files changed, 69 insertions(+), 19 deletions(-) diff --git a/.github/actions/install-pkg/action.yml b/.github/actions/install-pkg/action.yml index af1ebfe7..5e8bd9e4 100644 --- a/.github/actions/install-pkg/action.yml +++ b/.github/actions/install-pkg/action.yml @@ -3,6 +3,7 @@ description: Install earthaccess Python package and testing dependencies inputs: python-version: + description: Version of Python to use required: true runs: @@ -16,7 +17,7 @@ runs: - name: Display full python version shell: bash id: full-python-version - run: echo "{version}=$(python -c "import sys; print('-'.join(str(v) for v in sys.version_info))")" >> $GITHUB_OUTPUT + run: echo "version=$(python -c "import sys; print('-'.join(str(v) for v in sys.version_info))")" >> $GITHUB_OUTPUT - name: Install package and test dependencies shell: bash diff --git a/.github/workflows/integration-test.yml b/.github/workflows/integration-test.yml index cb013525..fba60ccc 100644 --- a/.github/workflows/integration-test.yml +++ b/.github/workflows/integration-test.yml @@ -2,6 +2,7 @@ name: Integration Tests on: pull_request: + pull_request_target: push: branches: - main @@ -19,6 +20,25 @@ concurrency: jobs: integration-tests: + # + # This condition prevents DUPLICATE attempts to run integration tests for + # PRs coming from FORKS. + # + # When a PR originates from a fork, both a pull_request and a + # pull_request_target event are triggered. This means that without a + # condition, GitHub will attempt to run integration tests TWICE, once for + # each event. + # + # To prevent this, this condition ensures that integration tests are run + # in only ONE of the following cases: + # + # 1. The event is NOT a pull_request. This covers the case when the event + # is a pull_request_target (i.e., a PR from a fork), as well as all + # other cases listed in the "on" block at the top of this file. + # 2. The event IS a pull_request AND the base repo and head repo are the + # same (i.e., the PR is NOT from a fork). + # + if: github.event_name != 'pull_request' || github.event.pull_request.base.repo.full_name == github.event.pull_request.head.repo.full_name runs-on: ubuntu-latest strategy: matrix: @@ -26,13 +46,35 @@ jobs: fail-fast: false steps: - - uses: actions/checkout@v4 + - name: Fetch user permission + id: permission + uses: actions-cool/check-user-permission@v2 + with: + require: write + username: ${{ github.triggering_actor }} + + - name: Check user permission + if: ${{ steps.permission.outputs.require-result == 'false' }} + # If the triggering actor does not have write permission (i.e., this is a + # PR from a fork), then we exit, otherwise most of the integration tests will + # fail because they require access to secrets. In this case, a maintainer + # will need to make sure the PR looks safe, and if so, manually re-run the + # failed pull_request_target jobs. + run: | + echo "User **${{ github.triggering_actor }}** does not have permission to run integration tests." >> $GITHUB_STEP_SUMMARY + echo "A maintainer must perform a security review and re-run this build, if the code is safe." >> $GITHUB_STEP_SUMMARY + echo "See [Keeping your GitHub Actions and workflows secure Part 1: Preventing pwn requests](https://securitylab.github.com/resources/github-actions-preventing-pwn-requests)." >> $GITHUB_STEP_SUMMARY + exit 1 + + - name: Checkout source + uses: actions/checkout@v4 - - uses: ./.github/actions/install-pkg + - name: Install package with dependencies + uses: ./.github/actions/install-pkg with: python-version: ${{ matrix.python-version }} - - name: Test + - name: Run integration tests env: EARTHDATA_USERNAME: ${{ secrets.EDL_USERNAME }} EARTHDATA_PASSWORD: ${{ secrets.EDL_PASSWORD }} @@ -40,7 +82,7 @@ jobs: EARTHACCESS_TEST_PASSWORD: ${{ secrets.EDL_PASSWORD }} run: ./scripts/integration-test.sh - - name: Upload coverage + - name: Upload coverage report # Don't upload coverage when using the `act` tool to run the workflow locally if: ${{ !env.ACT }} uses: codecov/codecov-action@v4 diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index af5fd1f6..1d6250d4 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -16,7 +16,8 @@ jobs: fail-fast: false steps: - - uses: actions/checkout@v4 + - name: Checkout sources + uses: actions/checkout@v4 - uses: ./.github/actions/install-pkg with: diff --git a/.gitignore b/.gitignore index 356afb4f..d0ee3ea9 100644 --- a/.gitignore +++ b/.gitignore @@ -2,6 +2,7 @@ .ipynb_checkpoints .python-version .mypy_cache +.nox/ __pycache__ .pytest_cache htmlcov diff --git a/docs/contributing/development.md b/docs/contributing/development.md index 497b5391..1c4baa1a 100644 --- a/docs/contributing/development.md +++ b/docs/contributing/development.md @@ -33,19 +33,20 @@ environment for each run. ## Manual development environment setup -While `nox` is the fastest way to get started, you may soon find that you need a full -development environment, for example to test in a REPL. This development environment -also includes `nox`. +While `nox` is the fastest way to get started, you will likely need a full +development environment for making code contributions, for example to test in a +REPL, or to resolve references in your favorite IDE. This development +environment also includes `nox`. -Create and activate a virtual environment with `venv`, which comes by default with -Python, in the `.venv` directory: +Create and activate a virtual environment with `venv`, which comes by default +with Python, in the `.venv` directory: ```bash python -m venv .venv source .venv/bin/activate ``` -Install _earthaccess_ in editable mode with optional development dependencies: +Install `earthaccess` in editable mode with optional development dependencies: ```bash pip install --editable ".[dev,test,docs]" @@ -53,8 +54,8 @@ pip install --editable ".[dev,test,docs]" ??? note "For conda users" - For your convenience, there is a `environment.yml` file at the root of this - repository. You can create a dev environment quickly with: + For your convenience, there is an `environment.yml` file at the root of this + repository, allowing you to create a conda environment quickly, as follows: ```bash conda env create --file environment.yml @@ -62,6 +63,6 @@ pip install --editable ".[dev,test,docs]" ## Managing Dependencies -If you need to add a new dependency, edit `pyproject.toml` and insert the dependency in -the correct location (either in the `dependencies` array or -`[project.optional-dependencies]`. +If you need to add a new dependency, edit `pyproject.toml` and insert the +dependency in the correct location (either in the `dependencies` array or under +`[project.optional-dependencies]`). diff --git a/environment.yml b/environment.yml index a7a5dd01..e0eb49b3 100644 --- a/environment.yml +++ b/environment.yml @@ -9,3 +9,7 @@ dependencies: - pip - pip: - --editable .[dev,test,docs] +variables: + # Allow pip installs when conda environment is active + PIP_REQUIRE_VENV: 0 + PIP_REQUIRE_VIRTUALENV: 0 diff --git a/noxfile.py b/noxfile.py index cadc109d..257b0533 100644 --- a/noxfile.py +++ b/noxfile.py @@ -8,7 +8,7 @@ DIR = Path(__file__).parent.resolve() nox.needs_version = ">=2024.3.2" -nox.options.sessions = ["typecheck", "test_unit"] +nox.options.sessions = ["typecheck", "tests"] nox.options.default_venv_backend = "uv|virtualenv" @@ -20,7 +20,7 @@ def typecheck(session: nox.Session) -> None: @nox.session -def test_unit(session: nox.Session) -> None: +def tests(session: nox.Session) -> None: """Run the unit tests.""" session.install("--editable", ".[test]") session.run("pytest", "tests/unit", *session.posargs)