From b2203f74c68b63d65898b8e031aff02e8a654696 Mon Sep 17 00:00:00 2001 From: Joseph H Kennedy Date: Wed, 2 Oct 2024 15:15:10 -0800 Subject: [PATCH 01/11] Update contributing docs to be more welcoming --- .github/pull_request_template.md | 1 - docs/contributing/development.md | 94 +++++++++++++---- docs/contributing/index.md | 133 ++++++++++++------------- docs/contributing/maintainers-guide.md | 2 +- mkdocs.yml | 2 + noxfile.py | 7 ++ scripts/build-docs.sh | 3 - scripts/docs-live.sh | 5 - 8 files changed, 146 insertions(+), 101 deletions(-) delete mode 100755 scripts/build-docs.sh delete mode 100755 scripts/docs-live.sh diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 8af03cce..056c0968 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -24,7 +24,6 @@ created the PR as a non-draft, don't worry, you can still change it to a draft u - [ ] Please review our [contributing documentation](https://earthaccess.readthedocs.io/en/latest/contributing/) 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". Example PRs: [#763](https://github.com/nsidc/earthaccess/pull/763) diff --git a/docs/contributing/development.md b/docs/contributing/development.md index 1c4baa1a..f214ed94 100644 --- a/docs/contributing/development.md +++ b/docs/contributing/development.md @@ -2,8 +2,11 @@ ## Getting the code -1. Fork [nsidc/earthaccess](https://github.com/nsidc/earthaccess) -1. Clone your fork (`git clone git@github.com:{my-username}/earthaccess`) +1. Fork [nsidc/earthaccess](https://github.com/nsidc/earthaccess/fork) +1. Clone your fork + ```bash + git clone git@github.com:{my-username}/earthaccess + ``` In order to develop new features or fix bugs etc. we need to set up a virtual environment and install the library locally. @@ -24,8 +27,8 @@ specific jobs: ```console $ nox -s typecheck # Typecheck only $ nox -s tests # Python tests -$ nox -s build_docs -- --serve # Build and serve the docs -$ nox -s build_pkg # Make an SDist and wheel +$ nox -s serve_docs # build and serve the docs +$ nox -s build_pkg # Make an SDist and Wheel ``` Nox handles everything for you, including setting up a temporary virtual @@ -36,33 +39,86 @@ environment for each run. 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`. +environment also includes `nox`. You can create it with `venv`, `conda`, or `mamba`. -Create and activate a virtual environment with `venv`, which comes by default -with Python, in the `.venv` directory: +=== "`venv`" -```bash -python -m venv .venv -source .venv/bin/activate -``` + `venv` is a virtual environment manager that's built into Python. -Install `earthaccess` in editable mode with optional development dependencies: + Create and activate the development environment with: -```bash -pip install --editable ".[dev,test,docs]" -``` + ```bash + python -m venv .venv + source .venv/bin/activate + ``` + + Then install `earthaccess` into the environment in editable mode with the optional development dependencies: + + ```bash + pip install --editable ".[dev,test,docs]" + ``` -??? note "For conda users" - 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: +=== "`conda`/`mamba`" + + `conda` and `mamba` are open-source package and environment managers that are language and platform agnostic. + `mamba` is a newer and faster re-implementation of `conda` -- you can use either `conda` or `mamba` + in the commands below. + + Create and activate the development environment with: ```bash - conda env create --file environment.yml + mamba env update -f environment.yml + mamba activate earthaccess ``` + This will update (or create if missing) the `earthaccess` environment and active it. The `earthaccess` package will + be installed into the environment in editable mode with the optional development dependencies. + ## 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 under `[project.optional-dependencies]`). + +## Usage of Pre-Commit + +To maintain code quality, we use pre-commit for automated checks before committing changes. We recommend you install +and configure pre-commit so you can format and lint as you go instead of waiting for CI/CD check failures and +having to make significant changes to get the checks to pass. + +To set up pre-commit, follow these steps: + +- `pip install pre-commit` ([official installation docs](https://pre-commit.com/#install)) +- `pre-commit install` to enable it to run automatically +- `pre-commit run -a` to run it manually + +We have included type stubs for the untyped `python-cmr` library, which we intend to eventually upstream. +Since `python-cmr` exposes the `cmr` package, the stubs appear under `stubs/cmr`. + + +## Documentation + +To work on documentation locally, we provide a script that will automatically re-render the docs when you make changes: + +``` +nox -s serve_docs +``` + +MkDocs does not support incremental rebuilds and will execute every Jupyter Notebook every time it builds a new +version of the site, which can be quite slow. To speed up the build, you can pass MkDocs these options: + +``` +nox -s serve_docs -- --dirty --no-strict +``` + +!!! warning + + Our mkdocs setup has a known limitation: the hot reloader won't auto-reload when changing docstrings. + To see updates, manually rebuild and re-serve docs. We're working to improve the developer experience and + appreciate your patience. + +### Documentation Style + +To ensure that our code is well-documented and easy to understand, we use [Google-style docstrings](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) to document +all functions, classes, and methods in this library. diff --git a/docs/contributing/index.md b/docs/contributing/index.md index 081da2df..3223d156 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -1,99 +1,88 @@ # Contributing -When contributing to this repository, please first discuss the change you wish to make -with the community and maintainers via -[a GitHub issue](https://github.com/nsidc/earthaccess/issues), -[a GitHub Discussion](https://github.com/nsidc/earthaccess/discussions), -or [any other method](our-meet-ups.md). +Thank you for your interest in contributing to _earthaccess_! We're excited for your contribution, +whether you're finding bugs, adding new features, fixing anything broken, or improving documentation. -Please note that we have a [code of conduct](./code-of-conduct.md). Please follow it in all of your interactions with the project. +When contributing we recommend: -## First Steps to contribute +- reading the contributing guide all the way though once before starting +- searching through issues, discussions, and pull requests to see if your contribution has already been discussed + so you don't duplicate work -First, read the documentation! +Then, you can: -When you feel comfortable, fork this repository and set up your development environment. -Don't forget to run our suite of checks (see [development environment -documentation](./development.md) for details)! +- Open [a GitHub issue](https://github.com/nsidc/earthaccess/issues) to report a bug, unexpected behavior, a stumbling block in our documentation, or any + other problem. +- Open [a Q&A GitHub Discussion](https://github.com/nsidc/earthaccess/discussions/categories/new?category=q-a) to ask + questions, share insights, or connect with others about Earth data access (broadly) +- Open [an Ideas GitHub Discussion](https://github.com/nsidc/earthaccess/discussions/new?category=ideas) to suggest + new features or improvements, and find collaborators and coordinate the work +- Join [a "hack day"](our-meet-ups.md) to meat other users/developers/maintainers and get help on, or give help to, + anything related to Earth data access -## Sharing your work with us on GitHub +You can also directly [open a pull request](#steps-to-a-pull-request) after you've reviewed this whole contributing guide. -From here, you might want to fix and issue or bug, or add a new feature. Jump to the -relevant section to proceed. +If you're not sure what to do, _don't worry_, and just pick whichever suites you best. -### Fixing an Issue or Bug +!!! note + + We have a [code of conduct](./code-of-conduct.md). Please follow it in all of your interactions with the project. -- Create a GitHub issue with a - [minimal reproducible example](https://en.wikipedia.org/wiki/Minimal_reproducible_example), - a.k.a Minimal Complete Verifiable Example (MCVE), Minimal Working Example (MWE), - SSCCE (Short, Self Contained, Complete Example), or "reprex". -- Create a branch to resolve your issue -- Run the unit tests successfully in your branch -- Create one or more new tests to demonstrate the bug and observe them fail -- Update the relevant code to fix the issue -- Successfully run your new unit tests +## Steps to a Pull Request -Once you've completed these steps, you are ready to submit your contribution. +First, [fork this repository](https://github.com/nsidc/earthaccess/fork) and set up your [development environment](./development.md). -### Contributing a New Feature +From here, you might want to fix and issue or bug, or add a new feature. Jump to the +relevant tab to proceed. -- Create an issue and discuss the feature's scope and its fit for this package with the team -- Create a branch for your new feature in your fork -- Run the unit tests successfully in your branch -- Write the code to implement your new feature in a backwards compatible manner -- Create at least one test that exercises your feature and run the test suite as you go +!!! tip -Once you've completed these steps, you are ready to submit your contribution. + The small the pull request, the easier it is to review and test, and the more likely it is to be successful. + For large contributions, consider opening [an Ideas GitHub Discussion](https://github.com/nsidc/earthaccess/discussions/new?category=ideas) + or [coming to a "hack day"](our-meet-ups.md) and descibing your contribution so we can help guide and/or collaborate + on the work. -### Contributing to Documentation +=== "Fixing an Issue or Bug" -#### Documentation Style + - Create a [minimal reproducible example](https://en.wikipedia.org/wiki/Minimal_reproducible_example), a.k.a. a Minimal Complete Verifiable Example (MCVE), + a Minimal Working Example (MWE), an SSCCE (Short, Self Contained, Complete Example), or a "reprex", + and include it in [a GitHub issue](https://github.com/nsidc/earthaccess/issues) (recommended) or in your pull request. + - Create a branch to resolve your issue + - Run the unit tests successfully in your branch + - Create one or more new tests to demonstrate the bug and observe them fail + - Update the relevant code to fix the issue + - Successfully run your new unit tests + - Lint and format your code with [Pre-Commit](development.md#usage-of-pre-commit) + - Described your changes in the `CHANGELOG.md` -To ensure that our code is well-documented and easy to understand, we use [Google-style docstrings](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) to document all functions, classes, and methods in this library. +=== "Contributing a New Feature" -#### Locally rendering the documentation + - We recommend you create [an Ideas GitHub Discussion](https://github.com/nsidc/earthaccess/discussions/new?category=ideas) + describing the feature's scope and it's fit for this package with the team + - Create a branch for your new feature in your fork + - Run the unit tests successfully in your branch + - Write the code to implement your new feature in a backwards compatible manner + - Create at least one test that exercises your feature and run the test suite + - Lint and format your code with [Pre-Commit](development.md#usage-of-pre-commit) + - Described your changes in the `CHANGELOG.md` -To work on documentation locally, we provide a script that will automatically re-render the docs when you make changes: +=== "Contributing to Documentation" -``` -./scripts/docs-live.sh -``` - -If you encounter any issues while setting up the documentation using the provided steps, please refer to our [tutorial]( https://www.youtube.com/watch?v=mNjlMZ4F3So) for additional guidance. - -##### Caveats and considerations - -Our mkdocs setup has a known limitation: the hot reloader won't auto-reload when changing docstrings. To see updates, manually rebuild and re-serve docs. We're working to improve the developer experience and appreciate your patience. + - Create a branch for your documentation changes in your fork + - Update the documentation [following our style guide](development.md#documentation) + - Preview the documentation [by rendering it locally](development.md#documentation) + - Described your changes in the `CHANGELOG.md` +Once you've completed these steps, you are ready to submit your pull request. ## Submitting your contribution -- Run all unit tests successfully in your branch -- Lint and format your code. See below. -- Update the documentation and CHANGELOG.md -- Submit the fix to the problem as a pull request -- Include an explanation of what you did and why in the pull request - -### Please format and lint as you go - - -#### Usage of Pre-Commit - -To maintain code quality, we use pre-commit for automated checks before committing changes. Install and configure pre-commit to ensure high-quality contributions. - -To set up pre-commit, follow these steps: - -- `pip install pre-commit` ([official installation docs](https://pre-commit.com/#install)) -- `pre-commit install` to enable it to run automatically -- `pre-commit run -a` to run it manually - - -We have included type stubs for the untyped `python-cmr` library, which we intend to eventually upstream. Since `python-cmr` exposes the `cmr` package, the stubs appear under `stubs/cmr`. +When you're ready to submit your pull request, first open a draft pull request and confirm that: -## Pull Request process +- You've included an explanation of what you did and why in the pull request +- All unit tests run successfully in your branch +- Your code is linted and formated correctly +- The documentation and `CHANGELOG.md` has been updated appropriately -Fork the repository using the "Fork" button on the [repository -homepage](https://github.com/nsidc/earthaccess), create a branch with your changes in the fork, then open -a draft pull request from your fork. Starting a pull request provides additional instructions and requirements, and -there is no harm in starting a draft pull request while still developing. +Then you can mark the pull request as ready for review! diff --git a/docs/contributing/maintainers-guide.md b/docs/contributing/maintainers-guide.md index bfbbbf47..c9d7d3cf 100644 --- a/docs/contributing/maintainers-guide.md +++ b/docs/contributing/maintainers-guide.md @@ -8,7 +8,7 @@ This page offers guidance to project maintainers regarding our setup procedures, If you are interested in becoming a maintainer, you can join our community. Maintainers have several important responsibilities, so please read on to understand the role. -Also, if you're interested in helping managing issues with labels and interacting with incoming requests, you can have a "triager" role! +Also, if you're interested in helping manage issues with labels and interacting with incoming requests, you can have a "triager" role! To get permissions, please start by participating on GitHub by answering questions, reviewing PRs, or contributing code or documentation. Once you're feeling comfortable, you can ask any of our maintainers for permissions by `@`ing them on GitHub. diff --git a/mkdocs.yml b/mkdocs.yml index c7655fff..1eb56098 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -120,6 +120,8 @@ markdown_extensions: - pymdownx.inlinehilite - pymdownx.snippets - pymdownx.superfences + - pymdownx.tabbed: + alternate_style: true watch: - docs diff --git a/noxfile.py b/noxfile.py index 257b0533..c85e98c4 100644 --- a/noxfile.py +++ b/noxfile.py @@ -35,3 +35,10 @@ def build_pkg(session: nox.Session) -> None: session.install("build") session.run("python", "-m", "build") + + +@nox.session +def serve_docs (session: nox.Session) -> None: + """Build the documentation and serve it.""" + session.install("--editable", ".[docs]") + session.run("mkdocs", "serve", *session.posargs) diff --git a/scripts/build-docs.sh b/scripts/build-docs.sh deleted file mode 100755 index 4cccdd2c..00000000 --- a/scripts/build-docs.sh +++ /dev/null @@ -1,3 +0,0 @@ -#!/usr/bin/env bash - -python -m mkdocs build diff --git a/scripts/docs-live.sh b/scripts/docs-live.sh deleted file mode 100755 index f9f1b9de..00000000 --- a/scripts/docs-live.sh +++ /dev/null @@ -1,5 +0,0 @@ -#!/usr/bin/env bash -set -ex - -# HACK: --no-strict is on because --dirtyreload ALWAYS throws errors. Better solution? -mkdocs serve --dev-addr 0.0.0.0:8008 --dirtyreload --no-strict From 3bc29c5810660dc13501bf57154a47e000844ed1 Mon Sep 17 00:00:00 2001 From: Joseph H Kennedy Date: Wed, 2 Oct 2024 16:38:15 -0800 Subject: [PATCH 02/11] fix: GH admonitions -> MkDocs admonitions --- docs/contributing/releasing.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/contributing/releasing.md b/docs/contributing/releasing.md index 96f27e83..7461c110 100644 --- a/docs/contributing/releasing.md +++ b/docs/contributing/releasing.md @@ -1,7 +1,9 @@ # Release process -> :memo: The versioning scheme we use is [SemVer](http://semver.org/). Note that until -> we agree we're ready for v1.0.0, we will not increment the major version. +!!! info + + The versioning scheme we use is [SemVer](http://semver.org/). Note that until + we agree we're ready for v1.0.0, we will not increment the major version. 1. Ensure all desired features are merged to `main` branch and `CHANGELOG.md` is updated. **Do not** edit the `Unreleased` header in the CHANGELOG -- the next step @@ -49,8 +51,10 @@ - Zenodo will create a new DOI. - GitHub Actions will publish a PyPI release. -1. Once the package is visible on PyPI, check it's installable with `pip install - earthaccess==vX.Y.Z`. +1. Once the package is visible on PyPI, check it's installable with + ``` + python -m pip install earthaccess==vX.Y.Z + ``` 1. After the package is released on PyPI, follow the [conda-forge maintainer process](https://conda-forge.org/docs/maintainer/) to release @@ -58,7 +62,7 @@ !!! note - :memo: `earthaccess` is published to conda-forge through the + `earthaccess` is published to conda-forge through the [earthdata-feedstock](https://github.com/conda-forge/earthdata-feedstock), as this project was renamed early in its life. The conda package is named `earthaccess`. From 2b9e199339fcb0c2e6538b3620a0da2fa8b18fd2 Mon Sep 17 00:00:00 2001 From: Joseph H Kennedy Date: Wed, 2 Oct 2024 16:58:06 -0800 Subject: [PATCH 03/11] invoke pip correctly --- README.md | 2 +- docs/contributing/development.md | 4 ++-- docs/quick-start.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 2e810078..0489067b 100644 --- a/README.md +++ b/README.md @@ -51,7 +51,7 @@ During several workshops organized by NASA Openscapes, the need to provide easy- To install `earthaccess` go to your terminal and install it using `pip`: ``` -pip install earthaccess +python -m pip install earthaccess ``` diff --git a/docs/contributing/development.md b/docs/contributing/development.md index f214ed94..a484ac18 100644 --- a/docs/contributing/development.md +++ b/docs/contributing/development.md @@ -55,7 +55,7 @@ environment also includes `nox`. You can create it with `venv`, `conda`, or `mam Then install `earthaccess` into the environment in editable mode with the optional development dependencies: ```bash - pip install --editable ".[dev,test,docs]" + python -m pip install --editable ".[dev,test,docs]" ``` @@ -89,7 +89,7 @@ having to make significant changes to get the checks to pass. To set up pre-commit, follow these steps: -- `pip install pre-commit` ([official installation docs](https://pre-commit.com/#install)) +- `python -m pip install pre-commit` ([official installation docs](https://pre-commit.com/#install)) - `pre-commit install` to enable it to run automatically - `pre-commit run -a` to run it manually diff --git a/docs/quick-start.md b/docs/quick-start.md index 46f17b0a..462e2154 100644 --- a/docs/quick-start.md +++ b/docs/quick-start.md @@ -21,7 +21,7 @@ conda install -c conda-forge earthaccess #### Using `pip` ```bash -pip install earthaccess +python -m pip install earthaccess ``` From 8697350dcdb398c536f2a38dc5d31cde872c0482 Mon Sep 17 00:00:00 2001 From: Joseph H Kennedy Date: Wed, 2 Oct 2024 17:00:19 -0800 Subject: [PATCH 04/11] fix spelling --- docs/contributing/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/contributing/index.md b/docs/contributing/index.md index 3223d156..af82846e 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -40,7 +40,7 @@ relevant tab to proceed. The small the pull request, the easier it is to review and test, and the more likely it is to be successful. For large contributions, consider opening [an Ideas GitHub Discussion](https://github.com/nsidc/earthaccess/discussions/new?category=ideas) - or [coming to a "hack day"](our-meet-ups.md) and descibing your contribution so we can help guide and/or collaborate + or [coming to a "hack day"](our-meet-ups.md) and describing your contribution so we can help guide and/or collaborate on the work. === "Fixing an Issue or Bug" @@ -82,7 +82,7 @@ When you're ready to submit your pull request, first open a draft pull request a - You've included an explanation of what you did and why in the pull request - All unit tests run successfully in your branch -- Your code is linted and formated correctly +- Your code is linted and formatted correctly - The documentation and `CHANGELOG.md` has been updated appropriately Then you can mark the pull request as ready for review! From e4b574cc03600885c865eb4845a6169d7ec08206 Mon Sep 17 00:00:00 2001 From: Joseph H Kennedy Date: Wed, 2 Oct 2024 17:02:17 -0800 Subject: [PATCH 05/11] whitespace --- docs/contributing/index.md | 2 +- docs/contributing/releasing.md | 2 +- noxfile.py | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/contributing/index.md b/docs/contributing/index.md index af82846e..07609bab 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -25,7 +25,7 @@ You can also directly [open a pull request](#steps-to-a-pull-request) after you' If you're not sure what to do, _don't worry_, and just pick whichever suites you best. !!! note - + We have a [code of conduct](./code-of-conduct.md). Please follow it in all of your interactions with the project. ## Steps to a Pull Request diff --git a/docs/contributing/releasing.md b/docs/contributing/releasing.md index 7461c110..0f24cad1 100644 --- a/docs/contributing/releasing.md +++ b/docs/contributing/releasing.md @@ -51,7 +51,7 @@ - Zenodo will create a new DOI. - GitHub Actions will publish a PyPI release. -1. Once the package is visible on PyPI, check it's installable with +1. Once the package is visible on PyPI, check it's installable with ``` python -m pip install earthaccess==vX.Y.Z ``` diff --git a/noxfile.py b/noxfile.py index c85e98c4..858bedc9 100644 --- a/noxfile.py +++ b/noxfile.py @@ -38,7 +38,7 @@ def build_pkg(session: nox.Session) -> None: @nox.session -def serve_docs (session: nox.Session) -> None: +def serve_docs(session: nox.Session) -> None: """Build the documentation and serve it.""" session.install("--editable", ".[docs]") session.run("mkdocs", "serve", *session.posargs) From e8769752916477d1c69f128a6563a88e336f5b6b Mon Sep 17 00:00:00 2001 From: Joseph H Kennedy Date: Wed, 2 Oct 2024 17:30:28 -0800 Subject: [PATCH 06/11] Update docs/contributing/development.md --- 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 a484ac18..0ec51ce0 100644 --- a/docs/contributing/development.md +++ b/docs/contributing/development.md @@ -27,7 +27,7 @@ specific jobs: ```console $ nox -s typecheck # Typecheck only $ nox -s tests # Python tests -$ nox -s serve_docs # build and serve the docs +$ nox -s serve_docs # Build and serve the docs $ nox -s build_pkg # Make an SDist and Wheel ``` From 93d6a4884570ac26e992d9c6cb94e2f8967b25ef Mon Sep 17 00:00:00 2001 From: Joseph H Kennedy Date: Fri, 4 Oct 2024 06:03:04 -0800 Subject: [PATCH 07/11] Apply suggestions from code review Co-authored-by: Matt Fisher --- docs/contributing/development.md | 8 +++++--- docs/contributing/index.md | 24 ++++++++++++------------ 2 files changed, 17 insertions(+), 15 deletions(-) diff --git a/docs/contributing/development.md b/docs/contributing/development.md index 0ec51ce0..eaafd6b0 100644 --- a/docs/contributing/development.md +++ b/docs/contributing/development.md @@ -2,8 +2,8 @@ ## Getting the code -1. Fork [nsidc/earthaccess](https://github.com/nsidc/earthaccess/fork) -1. Clone your fork +1. [Fork nsidc/earthaccess](https://github.com/nsidc/earthaccess/fork) +1. Clone your fork: ```bash git clone git@github.com:{my-username}/earthaccess ``` @@ -90,9 +90,11 @@ having to make significant changes to get the checks to pass. To set up pre-commit, follow these steps: - `python -m pip install pre-commit` ([official installation docs](https://pre-commit.com/#install)) -- `pre-commit install` to enable it to run automatically +- `pre-commit install` to enable it to run automatically for each commit - `pre-commit run -a` to run it manually +## Type stubs + We have included type stubs for the untyped `python-cmr` library, which we intend to eventually upstream. Since `python-cmr` exposes the `cmr` package, the stubs appear under `stubs/cmr`. diff --git a/docs/contributing/index.md b/docs/contributing/index.md index 07609bab..f5f83f97 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -17,12 +17,12 @@ Then, you can: questions, share insights, or connect with others about Earth data access (broadly) - Open [an Ideas GitHub Discussion](https://github.com/nsidc/earthaccess/discussions/new?category=ideas) to suggest new features or improvements, and find collaborators and coordinate the work -- Join [a "hack day"](our-meet-ups.md) to meat other users/developers/maintainers and get help on, or give help to, +- Join [a "hack day"](our-meet-ups.md) to meet other users/developers/maintainers and get help on, or give help to, anything related to Earth data access You can also directly [open a pull request](#steps-to-a-pull-request) after you've reviewed this whole contributing guide. -If you're not sure what to do, _don't worry_, and just pick whichever suites you best. +If you're not sure what to do, _don't worry_, and just pick whichever suits you best. The community will help you out! !!! note @@ -37,7 +37,7 @@ relevant tab to proceed. !!! tip - The small the pull request, the easier it is to review and test, and the more likely it is to be successful. + The smaller the pull request, the easier it is to review and test, and the more likely it is to be successful. For more details, check out this [helpful YouTube video by the author of pre-commit](https://www.youtube.com/watch?v=Gu6XrmfwivI). For large contributions, consider opening [an Ideas GitHub Discussion](https://github.com/nsidc/earthaccess/discussions/new?category=ideas) or [coming to a "hack day"](our-meet-ups.md) and describing your contribution so we can help guide and/or collaborate @@ -49,30 +49,30 @@ relevant tab to proceed. a Minimal Working Example (MWE), an SSCCE (Short, Self Contained, Complete Example), or a "reprex", and include it in [a GitHub issue](https://github.com/nsidc/earthaccess/issues) (recommended) or in your pull request. - Create a branch to resolve your issue - - Run the unit tests successfully in your branch + - Run the existing unit tests successfully in your branch - Create one or more new tests to demonstrate the bug and observe them fail - Update the relevant code to fix the issue - Successfully run your new unit tests - Lint and format your code with [Pre-Commit](development.md#usage-of-pre-commit) - - Described your changes in the `CHANGELOG.md` + - Describe your changes in the `CHANGELOG.md` === "Contributing a New Feature" - We recommend you create [an Ideas GitHub Discussion](https://github.com/nsidc/earthaccess/discussions/new?category=ideas) - describing the feature's scope and it's fit for this package with the team + describing the feature's scope and its fit for this package with the team. - Create a branch for your new feature in your fork - Run the unit tests successfully in your branch - - Write the code to implement your new feature in a backwards compatible manner + - Write the code to implement your new feature in a backwards compatible manner. If breaking changes are necessary, discuss your strategy with the team first. - Create at least one test that exercises your feature and run the test suite - - Lint and format your code with [Pre-Commit](development.md#usage-of-pre-commit) - - Described your changes in the `CHANGELOG.md` + - Lint and format your code with [pre-commit](development.md#usage-of-pre-commit) + - Describe your changes in the `CHANGELOG.md` === "Contributing to Documentation" - Create a branch for your documentation changes in your fork - Update the documentation [following our style guide](development.md#documentation) - - Preview the documentation [by rendering it locally](development.md#documentation) - - Described your changes in the `CHANGELOG.md` + - Preview the documentation [by rendering it locally](development.md#documentation). If you're not comfortable with this step, we'd rather you skip it and open a PR anyway! Our GitHub automations will generate a documentation preview. Please mark your PR as a draft until you've checked the preview and it looks OK. Don't hesitate to reach out for help! + - Describe your changes in the `CHANGELOG.md` Once you've completed these steps, you are ready to submit your pull request. @@ -85,4 +85,4 @@ When you're ready to submit your pull request, first open a draft pull request a - Your code is linted and formatted correctly - The documentation and `CHANGELOG.md` has been updated appropriately -Then you can mark the pull request as ready for review! +Then you can mark the pull request as ready for review! :tada: From a214c8ec7fa7fc7139c86c8414981b728a8a2202 Mon Sep 17 00:00:00 2001 From: Joseph H Kennedy Date: Fri, 4 Oct 2024 06:04:42 -0800 Subject: [PATCH 08/11] Update docs/contributing/development.md --- 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 eaafd6b0..bbccecd6 100644 --- a/docs/contributing/development.md +++ b/docs/contributing/development.md @@ -81,7 +81,7 @@ 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]`). -## Usage of Pre-Commit +## Usage of pre-commit To maintain code quality, we use pre-commit for automated checks before committing changes. We recommend you install and configure pre-commit so you can format and lint as you go instead of waiting for CI/CD check failures and From 8326c6d4d6838b4919c0c2649fcb18709affa71c Mon Sep 17 00:00:00 2001 From: Joseph H Kennedy Date: Fri, 4 Oct 2024 06:06:03 -0800 Subject: [PATCH 09/11] Update docs/contributing/index.md --- docs/contributing/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/index.md b/docs/contributing/index.md index f5f83f97..f63aa63e 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -53,7 +53,7 @@ relevant tab to proceed. - Create one or more new tests to demonstrate the bug and observe them fail - Update the relevant code to fix the issue - Successfully run your new unit tests - - Lint and format your code with [Pre-Commit](development.md#usage-of-pre-commit) + - Lint and format your code with [pre-commit](development.md#usage-of-pre-commit) - Describe your changes in the `CHANGELOG.md` === "Contributing a New Feature" From 5b88fa40296424c6f968105c07cfaee4ad6011c7 Mon Sep 17 00:00:00 2001 From: Joseph H Kennedy Date: Fri, 4 Oct 2024 06:11:55 -0800 Subject: [PATCH 10/11] whitespace --- docs/contributing/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/index.md b/docs/contributing/index.md index f63aa63e..c8916997 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -85,4 +85,4 @@ When you're ready to submit your pull request, first open a draft pull request a - Your code is linted and formatted correctly - The documentation and `CHANGELOG.md` has been updated appropriately -Then you can mark the pull request as ready for review! :tada: +Then you can mark the pull request as ready for review! :tada: From 93b59e8ada63cfb9e01ad1c93696860c13774085 Mon Sep 17 00:00:00 2001 From: Joseph H Kennedy Date: Fri, 4 Oct 2024 06:25:44 -0800 Subject: [PATCH 11/11] Update docs/contributing/index.md --- docs/contributing/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/index.md b/docs/contributing/index.md index c8916997..35a7cf89 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -85,4 +85,4 @@ When you're ready to submit your pull request, first open a draft pull request a - Your code is linted and formatted correctly - The documentation and `CHANGELOG.md` has been updated appropriately -Then you can mark the pull request as ready for review! :tada: +Then you can mark the pull request as ready for review! 🎉