From 467b3d7b2c0f7f5b7e4088f067699e28c1953e4e Mon Sep 17 00:00:00 2001 From: Sherwin-14 Date: Wed, 3 Jul 2024 18:49:29 +0530 Subject: [PATCH 1/8] Fleshed out contributing docs to include pre-commit,style,build info --- docs/contributing/index.md | 54 +++++++++++++++++++++++++++----------- 1 file changed, 39 insertions(+), 15 deletions(-) diff --git a/docs/contributing/index.md b/docs/contributing/index.md index 3d149637..72494f8a 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -6,7 +6,7 @@ with the community and maintainers via [a GitHub Discussion](https://github.com/nsidc/earthaccess/discussions), or [any other method](our-meet-ups.md). -Please note that we have a [code of conduct](./code-of-conduct.md). Please follow it in all of your interactions with the project. +Please note that we have a [code of conduct](/CODE_OF_CONDUCT.md). Please follow it in all of your interactions with the project. ## First Steps to contribute @@ -43,6 +43,28 @@ Once you've completed these steps, you are ready to submit your contribution. Once you've completed these steps, you are ready to submit your contribution. + +### ...to contribute to docs + +#### 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 + +#### Getting Help with Setup and Configuration + +To work on docs locally follow the steps below: + +- To setup the documentation, navigate to the scripts directory +- Run the `scripts/build-docs.sh` script to build the documentation +- Serve the documentation locally, using the `scripts/docs-live.sh` script + +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 dev experience and appreciate your patience. + + ## Submitting your contribution - Run all unit tests successfully in your branch @@ -53,18 +75,20 @@ Once you've completed these steps, you are ready to submit your contribution. ### Please format and lint as you go -```bash -make format lint -``` -We attempt to provide comprehensive type annotations within this repository. If -you do not provide fully annotated functions or methods, the `lint` command will -fail. Over time, we plan to increase type-checking strictness in order to -ensure more precise, beneficial type annotations. +#### 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` for Windows and for Linux refer to your distribution's package index +- `pre-commit install` to enable it to run automatically +- `pre-commit run -a` to run it manually + +We attempt to provide comprehensive type annotations within this repository. If you do not provide fully annotated functions or methods, the `lint` command will fail. Over time, we plan to increase type-checking strictness in order to ensure more precise, beneficial type annotations. -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`. +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`. ### Requirements to merge code (Pull Request Process) @@ -75,12 +99,12 @@ the stubs appear under `stubs/cmr`. ## Pull Request process 1. Ensure you include test coverage for all changes -1. Ensure your code is formatted properly following this document -1. Update the documentation and the `README.md` with details of changes to the +2. Ensure your code is formatted properly following this document +3. Update the documentation and the `README.md` with details of changes to the interface, this includes new environment variables, function names, decorators, etc. -1. Update `CHANGELOG.md` with details about your change in a section titled +4. Update `CHANGELOG.md` with details about your change in a section titled `Unreleased`. If one does not exist, please create one. -1. You may merge the Pull Request once you have the sign-off of another +5. You may merge the Pull Request once you have the sign-off of another developer, or if you do not have permission to do that, you may request the reviewer to merge it for you. From a2d9cc576a42aeb22fcefc226d9d6ca29704e476 Mon Sep 17 00:00:00 2001 From: Sherwin-14 Date: Thu, 4 Jul 2024 13:37:14 +0530 Subject: [PATCH 2/8] Made the necessary changes like adding proper headings, and grammar suggestions --- docs/contributing/index.md | 29 ++++++++++++++--------------- 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/docs/contributing/index.md b/docs/contributing/index.md index 72494f8a..c5c40455 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -19,7 +19,7 @@ Please note that we have a [code of conduct](/CODE_OF_CONDUCT.md). Please follow From here, you might want to fix and issue or bug, or add a new feature. Jump to the relevant section to proceed. -### ...to fix an issue or bug +### Fixing an Issue or Bug - Create a GitHub issue with a [minimal reproducible example](https://en.wikipedia.org/wiki/Minimal_reproducible_example), @@ -33,7 +33,7 @@ relevant section to proceed. Once you've completed these steps, you are ready to submit your contribution. -### ...to contribute a new feature +### Contributing a New Feature - 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 @@ -44,15 +44,15 @@ Once you've completed these steps, you are ready to submit your contribution. Once you've completed these steps, you are ready to submit your contribution. -### ...to contribute to docs +### Contributing to Documentation -#### Documentation Style +#### 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 +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. #### Getting Help with Setup and Configuration -To work on docs locally follow the steps below: +To work on documentation locally, follow these steps: - To setup the documentation, navigate to the scripts directory - Run the `scripts/build-docs.sh` script to build the documentation @@ -62,7 +62,7 @@ If you encounter any issues while setting up the documentation using the provide #### 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 dev experience and appreciate your patience. +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. ## Submitting your contribution @@ -78,9 +78,9 @@ Our mkdocs setup has a known limitation: the hot reloader won't auto-reload when #### 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 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: +To set up pre-commit, follow these steps: - `pip install pre-commit` for Windows and for Linux refer to your distribution's package index - `pre-commit install` to enable it to run automatically @@ -99,12 +99,11 @@ We have included type stubs for the untyped `python-cmr` library, which we inten ## Pull Request process 1. Ensure you include test coverage for all changes -2. Ensure your code is formatted properly following this document -3. Update the documentation and the `README.md` with details of changes to the - interface, this includes new environment variables, function names, - decorators, etc. -4. Update `CHANGELOG.md` with details about your change in a section titled +1. Ensure your code is formatted properly following this document +1. Update the documentation and the `README.md` with details of changes to the + interface, this includes new environment variables, function names,decorators, etc. +1. Update `CHANGELOG.md` with details about your change in a section titled `Unreleased`. If one does not exist, please create one. -5. You may merge the Pull Request once you have the sign-off of another +1. You may merge the Pull Request once you have the sign-off of another developer, or if you do not have permission to do that, you may request the reviewer to merge it for you. From ea3a9c256a5c60ef323b39ee37bdae9b2fab5a17 Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Tue, 9 Jul 2024 11:32:49 -0600 Subject: [PATCH 3/8] Adjust wording of subheaders --- 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 c5c40455..b312609d 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -50,7 +50,7 @@ Once you've completed these steps, you are ready to submit your contribution. 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. -#### Getting Help with Setup and Configuration +#### Locally rendering the documentation To work on documentation locally, follow these steps: @@ -60,7 +60,7 @@ To work on documentation locally, follow these steps: 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 +##### 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. From b62b5dd8d08d606c43f8eee9f080a6c40a0d2bbe Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Tue, 9 Jul 2024 11:33:34 -0600 Subject: [PATCH 4/8] Fix code of conduct link --- 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 b312609d..6a5abf5a 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -6,7 +6,7 @@ with the community and maintainers via [a GitHub Discussion](https://github.com/nsidc/earthaccess/discussions), or [any other method](our-meet-ups.md). -Please note that we have a [code of conduct](/CODE_OF_CONDUCT.md). Please follow it in all of your interactions with the project. +Please note that we have a [code of conduct](./code-of-conduct.md). Please follow it in all of your interactions with the project. ## First Steps to contribute From 59dabee37404403d16214d9086dcb79e66a94e02 Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Tue, 9 Jul 2024 11:34:17 -0600 Subject: [PATCH 5/8] Make the local documentation workflow more concise --- docs/contributing/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/contributing/index.md b/docs/contributing/index.md index 6a5abf5a..4df59b9b 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -52,11 +52,11 @@ To ensure that our code is well-documented and easy to understand, we use [Googl #### Locally rendering the documentation -To work on documentation locally, follow these steps: +To work on documentation locally, we provide a script that will automatically re-render the docs when you make changes: -- To setup the documentation, navigate to the scripts directory -- Run the `scripts/build-docs.sh` script to build the documentation -- Serve the documentation locally, using the `scripts/docs-live.sh` script +``` +./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. From b324ff8694dff32fc344c88da3b6b6e24edf930c Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Tue, 9 Jul 2024 11:34:41 -0600 Subject: [PATCH 6/8] Link to pre-commit install docs --- 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 4df59b9b..2f661f86 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -82,7 +82,7 @@ To maintain code quality, we use pre-commit for automated checks before committi To set up pre-commit, follow these steps: -- `pip install pre-commit` for Windows and for Linux refer to your distribution's package index +- `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 From d8f95114605cf5f9069c8430741f9dce714c2a70 Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Tue, 9 Jul 2024 11:35:12 -0600 Subject: [PATCH 7/8] Remove instructions referencing removed Make command instructions --- docs/contributing/index.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/contributing/index.md b/docs/contributing/index.md index 2f661f86..adabeda6 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -86,7 +86,6 @@ To set up pre-commit, follow these steps: - `pre-commit install` to enable it to run automatically - `pre-commit run -a` to run it manually -We attempt to provide comprehensive type annotations within this repository. If you do not provide fully annotated functions or methods, the `lint` command will fail. Over time, we plan to increase type-checking strictness in order to ensure more precise, beneficial type annotations. 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`. From f1176e615cd7a2813dcfbb79aa62585401180fe6 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Tue, 9 Jul 2024 17:47:27 +0000 Subject: [PATCH 8/8] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- 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 6ac83fd1..a8b9f624 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -94,4 +94,4 @@ We have included type stubs for the untyped `python-cmr` library, which we inten 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. \ No newline at end of file +there is no harm in starting a draft pull request while still developing.