Skip to content

Latest commit

 

History

History
112 lines (61 loc) · 4.43 KB

CONTRIBUTING.md

File metadata and controls

112 lines (61 loc) · 4.43 KB

Contributing

Thank you for considering contributing to our project! We are grateful for any time and effort you put into making this project better.

There are several ways you can contribute:

  • Submitting bug reports and feature requests

  • Submitting pull requests for code changes

  • Adding documentation or examples

  • Participating in discussions or providing feedback

Before contributing, please read this guide. If you have any questions, feel free to ask in our Slack or open a GitHub issue.

Submitting Bug Reports and Feature Requests

If you find a bug in the code or have an idea for a new feature, please search for an existing issue or open a new issue and provide as much detail as possible.

Submitting Pull Requests

We welcome pull requests for code changes! Before starting work on a pull request, please check with a maintainer to ensure that no one else is already working on the same change. Typically, this is done by posting a comment on the appropriate GitHub issue stating that you want to work on it.

Before working on a PR, you should first create a fork of gridstatus in your GitHub account and do your work in a new branch that you create in the fork. Read more here about collaborating with Pull Requests.

When submitting a pull request, please make sure to:

  • Write tests to cover any changes you make

  • Add any or update docstrings relevant to your change

  • Follow the existing code styles in place

  • Include a description of the changes you made and provide any additional information that will be helpful to the reviewer of your code

  • If relevant to users of the library, add details of your change to CHANGELOG.md.

Setting up a Development Environment

To set up a development environment for this project, you will need to:

  • Install Python 3.7 or higher and make sure java is installed on your system

  • Clone the repository. If you are working on a PR, you should clone your fork.

  • Install the project dependencies by running each of the following commands within a virtualenv

    make installdeps-dev
make installdeps-test
make installdeps-docs

  • Installing the dev dependencies enables a pre-commit hook that ensures linting has been run before committing

The best way to ensure everything is installed correctly by running running the tests. They should all pass.

Running Tests and Linting

To ensure that your changes are correct and follow our style guide, we ask you to run the tests and linting before submitting a pull request. You can use the following commands to do so:

# Run all tests
make test

# Run slow tests marked with @pytest.mark.slow
make test-slow

# Lint the code
make lint

# Fix linting errors
make lint-fix

We use pytest for testing, so you can also run the test directly with the pytest command.

Adding Documentation and Examples

To add documentation and examples to the project, follow these steps:

  1. Create a new .ipynb file with cell outputs saved to the appropriate folder in the docs/Examples directory. Make sure to save the outputs as you want them to be displayed, as the documentation build process will not run the notebook.

  2. Add a link to the notebook in docs/Examples/<folder>/index.md to include it in the table of contents.

  3. Build the documentation to confirm that the notebook is visible. You can do this locally by running make docs from the root directory. Read the Docs will also build the documentation on every pull request, which you can view by clicking on the details of the Read The Doc GitHub action from the PR.

We welcome contributions to the documentation and examples, and appreciate any efforts to improve them.

Code Review Process

All pull requests will be reviewed by one of our maintainers before being merged. We will review pull requests for:

  • Correctness

  • Code style

  • Test coverage

We may ask for additional changes or clarification before merging a pull request.

CI/CD

When you submit a PR, the following actions are automatically performed

  1. GitHub Actions runs tests the test in all support python versions
  2. GithHub Actions ensures the code is properly linted
  3. Our documentation host, Read the Docs, will build a copy of the docs for your PR