Merge branch 'nsidc:main' into format-and-lint-notebooks

.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

.github/pull_request_template.md

@@ -27,6 +27,7 @@ created the PR as a non-draft, don't worry, you can still change it to a draft u
 - [ ] 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".
+      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
@@ -35,6 +36,7 @@ created the PR as a non-draft, don't worry, you can still change it to a draft u
 - [ ] 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.
+      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.

.github/workflows/integration-test.yml

@@ -2,6 +2,7 @@ name: Integration Tests
 
 on:
   pull_request:
+  pull_request_target:
   push:
     branches:
       - main
@@ -19,28 +20,69 @@ 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:
         python-version: ["3.9", "3.10", "3.11", "3.12"]
       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 }}
           EARTHACCESS_TEST_USERNAME: ${{ secrets.EDL_USERNAME }}
           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

.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:

.gitignore

@@ -2,6 +2,7 @@
 .ipynb_checkpoints
 .python-version
 .mypy_cache
+.nox/
 __pycache__
 .pytest_cache
 htmlcov

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"
@@ -69,6 +76,10 @@
   ([#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
 

docs/contributing/development.md

@@ -33,35 +33,36 @@ 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]
+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
     ```
 
 ## 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]`).

docs/user_guide/backwards-compatibility.md

@@ -0,0 +1,48 @@
+# 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 [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 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. 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
+
+### Versioning
+
+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
+
+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
+
+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
+
+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 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.
+
+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](https://scientific-python.org/specs/spec-0000/) dependency version deprecation policy, which outlines the guidelines for upgrading dependencies of _earthaccess_.
+
+## Migration guides
+
+Under Development 🚧
+
+This section will contain migration guides for future releases. Check back soon for updates!

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

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"

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)