Skip to content

Commit

Permalink
Revised Contributing File (#81)
Browse files Browse the repository at this point in the history 
* start editing contributing file

* some formatting

* toc + more links and descriptions
  • Loading branch information
@elbeejay
elbeejay authored Feb 2, 2023
1 parent a82d23f commit 19541bd
Showing 1 changed file with 158 additions and 63 deletions.
221 changes: 158 additions & 63 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,72 +1,111 @@
# Contributing

Contributions to dataretrieval are welcome and greatly appreciated, but please
read this document before doing so.


## Ways to contribute
# Contributing Guidelines

Contributions to `dataretrieval` are welcome and greatly appreciated, but
please read this document for information on *how* to contribute.

`dataretrieval` broadly follows a ["forking" workflow](https://docs.github.com/en/get-started/quickstart/contributing-to-projects),
however writing code is not the only way to contribute.

---

## Table of Contents

- [Contributing Guidelines](#contributing-guidelines)
- [Table of Contents](#table-of-contents)
- [Bugs](#bugs)
- [Reporting Bugs](#reporting-bugs)
- [Fixing Bugs](#fixing-bugs)
- [Code Contributions](#code-contributions)
- [Implementing Features](#implementing-features)
- [Pull Request Guidelines](#pull-request-guidelines)
- [Coding Standards and Style](#coding-standards-and-style)
- [Style](#style)
- [Docstrings](#docstrings)
- [Quotes](#quotes)
- [Documentation](#documentation)
- [Contributing to the Documentation](#contributing-to-the-documentation)
- [Adding Examples to the Documentation](#adding-examples-to-the-documentation)
- [Feedback and Feature Requests](#feedback-and-feature-requests)
- [Submitting Feedback](#submitting-feedback)
- [Feature Requests](#feature-requests)
- [Acknowledgements](#acknowledgements)

---

## Bugs

### Reporting Bugs

Report bugs at https://github.com/thodson-usgs/dataretrieval/issues.
Report bugs at https://github.com/USGS-python/dataretrieval/issues.

When reporting a bug, please include:

* Detailed steps to reproduce the bug
* Your operating system name and version.
* Any details about your local setup that might be helpful in troubleshooting.
* Your operating system name and version
* The Python version, as well as information about your local Python
environment, such as the versions of installed packages
* Any additional details about your local setup that might be helpful in
troubleshooting

### Fixing Bugs

Look through the GitHub issues for bugs. Anything tagged as a "bug" is open to
whomever wants to fix it.
Look through the GitHub [issues](https://github.com/USGS-python/dataretrieval/issues)
for known and unresolved bugs. Any issues labeled "bug" that are unassigned,
are open for resolution. You are welcome to comment in the relevant issue to
state your intention to resolve the bug, which will help ensure there is no
duplication of the same work by multiple contributors.

---

## Code Contributions

Code contributions should be made following a ["forking" workflow](https://docs.github.com/en/get-started/quickstart/contributing-to-projects).
This means that first, one should *fork* the repository, essentially creating a
personal mirror of the project. Next, you will want to create a *feature branch*
in your fork, which you can push code changes to. Once you have completed your
modifications and additions, open a pull request from the *feature branch* in
your fork, to the original upstream repository.

### Implementing Features

Look through the GitHub issues for features. Anything tagged with "enhancement"
Look through the GitHub [issues](https://github.com/USGS-python/dataretrieval/issues)
for outstanding feature requests. Anything tagged with "enhancement"
and "please-help" is open to whomever wants to implement it.

Please do not combine multiple feature enhancements into a single pull request.


### Writing Documentation

dataretrieval could always use more documentation, whether as part of the
official docs, in docstrings, or even in blog posts or articles.


### Submiting Feedback

The best way to send feedback is to file an issue at
https://github.com/thodson-usgs/dataretrieval/issues.

If you are proposing a feature:

* Explain in detail how it would work.
* Keep the scope as narrow as possible, to make it easier to implement.


# Contributor Guidelines


## Pull Request Guidelines
### Pull Request Guidelines

Before you submit a pull request, check that it meets these guidelines:

1. Any pull request should include tests. However, a contribution with
no tests is preferablble to no contribution at all.
2. If the pull request adds functionality, the docs should be updated. Put
your new functionality into a function with a docstring, and add the
feature to the list in README.md.
3. The pull request should work for Python 3.4, 3.5, 3.6, and PyPy on
Appveyor and Travis CI.


## Coding Standards

* PEP8
* Docstrings should follow the numpy standard:
1. If the pull request adds or modifies package functionality, unit tests
should be written to test the new functionality
2. If the pull request adds or modifies functionality, the documentation should
be updated. To do so, either add or modify a functions docstring which will
automatically become part of the API documentation
3. The pull request should work for Python 3.7, 3.8, 3.9, 3.10 - refer to the
[python-package.yml file](https://github.com/USGS-python/dataretrieval/blob/master/.github/workflows/python-package.yml)
for the latest versions of Python being tested by the continuous integration
pipelines. This will be checked automatically by the CI pipelines once the
pull request is opened.

### Coding Standards and Style

Note that coding standards and style as described below are strong suggestions,
the `dataretrieval` project does not strictly lint or enforce style guidelines
via any automated processes or pipelines.

#### Style

* Attempt to write code following the [PEP8 style guidelines](https://peps.python.org/pep-0008/) as much as possible
* The public interace should emphasize functions over classes; however, classes
can and should be used internally and in tests
* Functions for downloading data from a specific web portal must be grouped
within their own submodule
* For example, all NWIS functions are located at `dataretrieval.nwis`

#### Docstrings
* Docstrings should follow the [numpy standard](https://numpydoc.readthedocs.io/en/v1.5.0/format.html):
* Example:
``` python
def foo(param1, param2):
Expand All @@ -85,7 +124,7 @@ Before you submit a pull request, check that it meets these guidelines:
-------
bool
True if successful, False otherwise.
Examples
--------
Examples should be written in doctest format and should demonstrate basic usage.
Expand All @@ -96,15 +135,17 @@ Before you submit a pull request, check that it meets these guidelines:
"""
```
* For more details see https://github.com/sphinx-doc/sphinx/blob/master/doc/ext/example_numpy.py
* The public interace should emphasize functions over classes; however, classes can and should be used internally and in tests.
* Functions for downloading data from a specific web portal must be grouped within their own submodule.
* For example, all NWIS functions are located at `dataretrieval.nwis`.

* Quotes via http://stackoverflow.com/a/56190/5549
#### Quotes

* Use double quotes around strings that are used for interpolation or that are natural language messages
* Use single quotes for small symbol-like strings (but break the rules if the strings contain quotes)
* Use triple double quotes for docstrings and raw string literals for regular expressions even if they aren't needed.
* Quote conventions follow http://stackoverflow.com/a/56190/5549:

* Use double quotes around strings that are used for interpolation or that
are natural language messages
* Use single quotes for small symbol-like strings (but break the rules if
the strings contain quotes)
* Use triple double quotes for docstrings and raw string literals for
regular expressions even if they aren't needed
* Example:

``` python
Expand All @@ -123,10 +164,64 @@ Before you submit a pull request, check that it meets these guidelines:
return re.search(r"(?i)(arr|avast|yohoho)!", message) is not None
```

* Write new code in Python 3.

Acknowledgements
================
This document was adapted from the cookiecutter project's CONTRIBUTING file, which resides at
https://github.com/audreyr/cookiecutter/blob/master/CONTRIBUTING.rst
Thank you to the Cookiecutter team for helping streamline open-source development for the masses.
---

## Documentation

### Contributing to the Documentation

Documentation is built using [sphinx](https://www.sphinx-doc.org/en/master/),
and is located within the `docs/source/` subdirectory in the repository.
Documentation is written using [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html).

Contributions to the documentation should be made in a similar fashion to code
contributions - by following a forking workflow. When opening a pull request
please be sure to have tested your documentation modifications locally, and
clearly describe what it is your proposed changes add or fix.

### Adding Examples to the Documentation

A number of examples are provided in the documentation in the form of Jupyter
notebooks. These example notebooks are all contained within the `demos/`
subdirectory of the repository. If you have an example use of the package you
would like to add to the documentation as a run and rendered notebook, you
will need to do the following (in a separate branch of the repository):

1. Add your notebook to the `demos/` subdirectory after clearing all outputs
2. Add a corresponding `.nblink` file to `docs/source/examples/` subdirectory,
see existing examples for reference, or refer to the [nbsphinx-link](https://nbsphinx-link.readthedocs.io/en/latest/) documentation.
3. Add the example and some text describing it to one of the `.rst` files in
the examples subdirectory.
4. Run the documentation locally to ensure it renders as you expect, and then
open a pull request wherein you describe the proposed addition.

---

## Feedback and Feature Requests

### Submitting Feedback

The best way to send feedback is to open an issue at
https://github.com/USGS-python/dataretrieval/issues.

Please be as clear as possible in your feedback, if you are reporting a bug
refer to [Reporting Bugs](#reporting-bugs).


### Feature Requests

To request or propose a new feature, open an issue at
https://github.com/USGS-python/dataretrieval/issues.

Please be sure to:
* Explain in detail how it would work, possibly with pseudo-code or an example
use-case
* Keep the scope of the proposed feature as narrow as possible
* Make clear whether you would like to implement this feature, you need help
devising the implementation, or you are unable to implement the feature
yourself but would like it as a user

---

## Acknowledgements
This document was adapted from the cookiecutter project's [CONTRIBUTING file](https://github.com/audreyr/cookiecutter/blob/master/CONTRIBUTING.rst).

0 comments on commit 19541bd

Please sign in to comment.