Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fleshed out contributing docs to include pre-commit,style,build info #744

Merged
merged 9 commits into from
Jul 9, 2024
53 changes: 38 additions & 15 deletions docs/contributing/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
mfisher87 marked this conversation as resolved.
Show resolved Hide resolved

## First Steps to contribute

Expand All @@ -19,7 +19,7 @@ Please note that we have a [code of conduct](./code-of-conduct.md). Please follo
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),
Expand All @@ -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
Expand All @@ -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.


### Contributing to Documentation

#### 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
mfisher87 marked this conversation as resolved.
Show resolved Hide resolved

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
- Serve the documentation locally, using the `scripts/docs-live.sh` script
mfisher87 marked this conversation as resolved.
Show resolved Hide resolved

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
mfisher87 marked this conversation as resolved.
Show resolved Hide resolved

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

- Run all unit tests successfully in your branch
Expand All @@ -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
mfisher87 marked this conversation as resolved.
Show resolved Hide resolved
- `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.
mfisher87 marked this conversation as resolved.
Show resolved Hide resolved

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)

Expand All @@ -77,8 +101,7 @@ the stubs appear under `stubs/cmr`.
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
interface, this includes new environment variables, function names,
decorators, etc.
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.
1. You may merge the Pull Request once you have the sign-off of another
Expand Down
Loading