Skip to content

Commit

Permalink
Merge pull request nsidc#744 from Sherwin-14/contrib
Browse files Browse the repository at this point in the history
Fleshed out contributing docs to include pre-commit,style,build info
  • Loading branch information
mfisher87 authored Jul 9, 2024
2 parents d4fd6a6 + f1176e6 commit f4caacb
Showing 1 changed file with 35 additions and 12 deletions.
47 changes: 35 additions & 12 deletions docs/contributing/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

#### Locally rendering the documentation

To work on documentation locally, we provide a script that will automatically re-render the docs when you make changes:

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


## Submitting your contribution

- Run all unit tests successfully in your branch
Expand All @@ -53,18 +75,19 @@ 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` ([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`.
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`.

## Pull Request process

Expand Down

0 comments on commit f4caacb

Please sign in to comment.