Merge pull request #837 from jhkennedy/issue-pr-guidance

Update contributing guide to be more friendly

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

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
 ```
 
 

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,88 @@ 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
+ python -m 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:
+
+- `python -m pip install pre-commit` ([official installation docs](https://pre-commit.com/#install))
+- `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`.
+
+
+## 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.

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 meet 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 suits you best. The community will help you out!
 
-### Fixing an Issue or Bug
+!!! note
 
-- 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
+ We have a [code of conduct](./code-of-conduct.md). Please follow it in all of your interactions with the project.
 
-Once you've completed these steps, you are ready to submit your contribution.
+## Steps to a Pull Request
 
-### Contributing a New Feature
+First, [fork this repository](https://github.com/nsidc/earthaccess/fork) and set up your [development environment](./development.md).
 
-- 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
+From here, you might want to fix and issue or bug, or add a new feature. Jump to the
+relevant tab to proceed.
 
-Once you've completed these steps, you are ready to submit your contribution.
+!!! tip
 
+ 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).
 
-### Contributing to Documentation
+ 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
+ on the work.
 
-#### Documentation Style
+=== "Fixing an Issue or Bug"
 
-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.
+ - 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 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)
+ - Describe your changes in the `CHANGELOG.md`
 
-#### Locally rendering the documentation
+=== "Contributing a New Feature"
 
-To work on documentation locally, we provide a script that will automatically re-render the docs when you make changes:
+ - We recommend you create [an Ideas GitHub Discussion](https://github.com/nsidc/earthaccess/discussions/new?category=ideas)
+  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. 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)
+ - Describe your changes in the `CHANGELOG.md`
 
-```
-./scripts/docs-live.sh
-```
+=== "Contributing to Documentation"
 
-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). 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.
 
 ## 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 formatted 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! 🎉

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.
 

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,16 +51,18 @@
   - 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
  the package on conda-forge.
 
  !!! 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`.

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
 ```
 
 

mkdocs.yml

@@ -120,6 +120,8 @@ markdown_extensions:
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences
+ - pymdownx.tabbed:
+ alternate_style: true
 
 watch:
  - docs

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)