Contributing
Thank you for your interest in contributing to iesopt
! This guide provides instructions on setting up your development environment and contributing code.
Setting up the development environment
Fork the Repository: First, fork the main repository on GitHub to your account.
Clone the Repository: Clone the forked repository to your local machine, by running
git clone https://github.com/your-username/iesopt.git cd iesopt
Setup environment and install Poetry:
conda create -n iesopt python=3.12 -y conda activate iesopt pip install poetry
Install Dependencies: Install all dependencies using Poetry, by running
poetry install
Pre-commit Hooks: To maintain code quality, install pre-commit hooks:
pre-commit install
Code formatting and linting
After installing pre-commit hooks before, all checks should be automatically run and applied when committing changes.
Manually running checks
You can either execute
pre-commit
This stashes all changes that you have not committed. If you want to check all files, as they are, you can do so by running:
pre-commit run --all
ruff
(our linter & formatter) should fix most mistakes automatically. codespell
(our spelling checker) however, will report on mistakes in the terminal, linking to their occurrence. Inspect them, and fix them accordingly. Consult their README if you (highly unlikely) encounter a word where it wrongfully triggers.
Running tests
Execute
pytest
This will print a coverage report, which looks like
Name Stmts Miss Cover
--------------------------------------------------
src/iesopt/__init__.py 33 4 88%
src/iesopt/general.py 0 0 100%
...
src/iesopt/util/logging.py 7 0 100%
src/iesopt/util/util.py 5 0 100%
--------------------------------------------------
TOTAL 417 172 59%
and tells you roughly how good each file is covered by automated tests. Further it creates a coverage.xml
file in the project root folder, that you can use. In VSCode
, the extension Coverage Gutters allows inspecting test coverage directly in your code editor. If you have it installed and loaded, simply hit Ctrl + Shift + 8
(if you are using default keybinds) to enable watching the coverage.
Making changes
Create a New Branch: Always create a new branch for your work:
git checkout -b new-fix-or-feature
Make Your Changes: Edit files and make your desired changes.
Test Your Changes: Run tests frequently to ensure nothing is broken.
Commit Your Changes: Follow conventional commit messages for clarity:
git commit -m "feat: added new feature X"
Push Your Changes: Push the changes to your fork:
git push origin new-fix-or-feature
Improving the documentation
Building locally
sphinx-build --nitpicky --fail-on-warning --fresh-env --keep-going --builder html docs/ docs/_build/html
You can omit the --fresh-env
option to not
--fresh-env, -E don't use a saved environment, always read all files
and alternatively use
make -C docs clean
to clean the docs
before rebuilding them.
Note on --keep-going
A final build of updates to the documentation, that is built using the --fail-on-warning
flag, should be done without
--keep-going
, to prevent skipping warnings/errors: Each warning (or subsequent error) should be properly resolved!
Submitting a pull request (PR)
Once your changes are pushed to your fork, you can submit a pull request to the main repository:
Open a Pull Request: Go to the main repository and click “New Pull Request.”
Follow the Template: Provide a clear title and description of your changes.
Respond to Feedback: Engage with reviewers and make requested changes promptly.
Code Style and Guidelines
Follow PEP 8: Ensure your code adheres to PEP 8.
Document Your Code: Provide docstrings for all functions, classes, and modules.
Write Tests: Include tests for new features and bug fixes.
Reporting issues
If you find any bugs or have feature requests, please report them via the issue tracker.