Contributing to pyEQL¶

Reporting Issues¶

You can help the project simply by using pyEQL and comparing the output to experimental data and/or other models and tools. If you encounter any bugs, packaging issues, feature requests, comments, or questions, please report them using the issue tracker on github.

Tip

Please don’t forget to include the closed issues in your search. Sometimes a solution was already reported, and the problem is considered solved.

New issue reports should include information about your programming environment (e.g., operating system, Python version) and steps to reproduce the problem. Please try also to simplify the reproduction steps to a very minimal example that still illustrates the problem you are facing. By removing other factors, you help us to identify the root cause of the issue.

Documentation Improvements¶

You can help improve pyEQL docs by making them more readable and coherent, or by adding missing information and correcting mistakes.

pyEQL documentation uses Sphinx as its main documentation compiler. This means that the docs are kept in the same repository as the project code, and that any documentation update is done in the same way was a code contribution.

Tip

Please notice that the [GitHub web interface] provides a quick way of propose changes in pyEQL’s files. While this mechanism can be tricky for normal code contributions, it works perfectly fine for contributing to the docs, and can be quite handy.

If you are interested in trying this method out, please navigate to the docs folder in the source [repository], find which file you would like to propose changes and click in the little pencil icon at the top, to open [GitHub’s code editor]. Once you finish editing the file, please write a message in the form at the bottom of the page describing which changes have you made and what are the motivations behind them and submit your proposal.

When working on documentation changes in your local machine, you can compile them using tox:

tox -e docs

then use Python’s built-in web server for a preview in your web browser (http://localhost:8000):

python3 -m http.server --directory 'docs/_build/html'

Contributing Code¶

To contribute bug fixes, documentation enhancements, or new code, please fork pyEQL and send us a pull request. It’s not as hard as it sounds! Beginning with version 0.6.0, we follow the GitHub flow workflow model.

The Scientific Python Guide is also an excellent technical reference for new and longtime developers.

Submit an issue¶

Before you work on any non-trivial code contribution it’s best to first create a report in the issue tracker to start a discussion on the subject. This often provides additional considerations and avoids unnecessary work.

Hacking pyEQL, step by step¶

Fork the pyEQL repository on Github
Clone your repository to a directory of your choice:
```
git clone https://github.com/<username>/pyEQL
```
Install the package and the test dependencies by running the following command from the repository directory:
```
pip install -e '.[testing]``
```
Create a branch for your work. Preferably, start your branch name with “feature-”, “fix-”, or “doc-” depending on whether you are contributing bug fixes, documentation or a new feature, e.g. prefix your branch with “fix-” or “doc-” as appropriate:
```
git checkout -b mybranch
```
or
```
git checkout -b doc-mydoc
```
or
```
git checkout -b feature-myfeature
```
Make changes to the code until you’re satisfied.
Push your work back to Github:
```
git push origin feature-myfeature
```
Create a pull request with your changes. See this tutorial for instructions.

Guidelines¶

Please abide by the following guidelines when contributing code to pyEQL:

All changes you make to pyEQL should be accompanied by unit tests and should not break existing tests. To run the full test suite, run pytest tests/ from the repository directory.
Code coverage should be maintained or increase. Each PR will report code coverage after the tests pass, but you can check locally using pytest-cov, by running pytest --cov tests/. To produce a detailed HTML report with line and branch coverage statistics, run pytest --cov-branch --cov=src/pyEQL --cov-report=html -n auto tests.
All code should include type hints and have internally consistent documentation for the inputs and outputs.
Use Google style docstrings
Lint your code with ruff by running ruff check --fix src/ from the repo directory. Alternatively, you can install the pre-commit hooks by running pre-commit install from the repository directory. This will prevent committing new changes until all linting errors are fixed.
Update the CHANGELOG.md file.
Ask questions and be open to feedback!

Documentation¶

Improvements to the documentation are most welcome! Our documentation system uses sphinx with the Sphinx-Immaterial theme. To edit the documentation locally, run tox -e autodocs from the repository root directory. This will serve the documents to http://localhost:8000/ so you can view them in your web browser. When you make changes to the files in the docs/ directory, the documentation will automatically rebuild and update in your browser (you might have to refresh the page to see changes).

Changelog¶

We keep a CHANGELOG.md file in the base directory of the repository. Before submitting your PR, be sure to update the CHANGELOG.md file under the “Unreleased” section with a brief description of your changes. Our CHANGELOG.md file loosely follows the Keep a Changelog format, beginning with v0.6.0.