Contributing¶
Scikit-shapes is open to external contributions. You can contribute with new features, bug fixing, typo fixing, documentation improvement or whatever you think could be improved.
The first step is to open an issue describing the problem you have or the modification you want to implement. The issue discussion will serve as a place to discuss about what to do next and to assign the work that has to be done.
Then, if modifications have to be done to the codebase, the following instructions are made to help you in the process of integrating new code to scikit-shapes the smoothest way as possible.
How to push new code to scikit-shapes¶
Our continuous integration workflow¶
Scikit-shapes is designed to become community-driven. It is a necessity to have an infrastructure that ease the integration of external code. The project infrastrucure is largely influenced by the guides from scientific-python: https://learn.scientific-python.org/
All new code should be tested and documented and must pass our CI:
The pre-commit hooks enforce some style requirements
Then, the unit and functional tests are run:
run the tests with pytest
create a code coverage report with pytest-cov
build the documentation with sphinx
Contributing with new code¶
If you want to contribute to scikit-shapes, the first step is to fork the main repository and create a local branch in which you will push your modification.
Test your modification locally¶
When you have a clone of your scikit-shapes branch on your system and have made some modifications to the codebase, you may want to test your modification locally
In a virtual environment¶
Install your local version of scikit-shapes. With the --editable argument, further changes to the codebase will modify also the skshapes package on your environment. Then you don’t need to re-install the package every time you make a change.
pip install --editable .
Once your local version of scikit-shapes is installed, install the tests and documentation dependencies by running:
pip install -r requirements_dev.txt
pip install -r requirements_docs.txt
Then, you can run :
the precommit hooks:
pre-commit install
pre-commit run --all-files
the tests (and see code coverage report in your browser)
pytest
firefox htmlcov/index.html # replace firefox by your web browser
the documentation building
# Build the documentation
sphinx-apidoc -o doc/source/api/ --module-first --force src/skshapes
sphinx-build -b html doc/source/ doc/_build/html
# Serve it locally
cd doc/_build/html
python -m http.server
Using nox¶
Nox is a solution to build virtual environment on-the-fly and run a sequence of instruction (a session). We provide three nox sessions, defined on the file noxfile.py, they can be run with the following instructions:
pip install nox
nox -s tests
nox -s documentation
nox -s precommit
nox # Run all the sessions
Note that running nox sessions for scikit-shapes is very time-consuming, because the library and its dependencies must be reinstalled every time a nox session is started (and scikit-shapes depends on pytorch). We recommend to configure a virtual environment.
Open a pull request¶
When you think your code is ready to be merged, open a pull request to the main branch. The pre-commit hooks and the tests will run and a coverage report will be issued. Your modifications need to be approved by a maintainer before being merged to the main repository. If needed, modifications can be done after the opening of the pull request, each new push to your local branch will trigger the checks again.