Ctrl+K

Contributing

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.9 or higher and make sure java is installed on your system

  • Fork the repository and clone it to your local machine. For a PR, create a new branch in your fork.

  • Install the project dependencies by running:

# Configure poetry to use a virtual environment
poetry config virtualenvs.in-project true
# Install the project dependencies
poetry install --all-extras

  • Activate the poetry shell by running poetry shell. This will run in a virtual environment with all the dependencies installed.

  • 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.

Environment Variables#

  • Copy .env.template into a new file called .env and fill in the appropriate values for the environment variables. .env should not be committed to the repository.

  • Fill out these variables if you want to use the EIA or ERCOT APIs. They should be available in the pipenv shell thanks to the poetry-dotenv-plugin plugin.

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 from within the poetry shell.

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

Contents