First and foremost: Thank you for your interest in
pystiche s development! We
appreciate all contributions be it code or something else.
pystiche uses the GitHub workflow
. Below is small guide how to make your first contribution.
pystiche officially supports Python
3.8. To ensure
backwards compatibility, the development should happen on the minimum Python
version, i. e.
Navigate to pmeier/pystiche on GitHub and click the Fork button in the top right corner.
Clone your fork to your local file system
git cloneto get a local copy of
pystiches repository that you can work on:$ PYSTICHE_ROOT="pystiche" $ git clone "https://github.com/pmeier/pystiche.git" $PYSTICHE_ROOT
Setup your development environment
$ cd $PYSTICHE_ROOT $ virtualenv .venv --prompt="(pystiche) " $ source .venv/bin/activate $ pip install -r requirements-dev.txt $ pre-commit install
pystiches development requirements are fairly lightweight, it is still recommended to install them in a virtual environment rather than system wide. If you do not have
virtualenvinstalled, you can do so by running
pip install --user virtualenv.
Create a branch for local development
git checkoutto create local branch with a descriptive name:$ PYSTICHE_BRANCH="my-awesome-feature-or-bug-fix" $ git checkout -b $PYSTICHE_BRANCH
Now make your changes. Happy Coding!
toxto run various checks
toxis equivalent to running$ tox -e lint-style $ tox -e lint-typing $ tox -e tests-integration $ tox -e tests-galleries $ tox -e tests-docs
You can find details what the individual commands do below of this guide.
Commit and push your changes
If all checks are passing you can commit your changes an push them to your fork:$ git add . $ git commit -m "Descriptive message of the changes made" $ git push -u origin $PYSTICHE_BRANCH
For larger changes, it is good practice to split them in multiple small commits rather than one large one. If you do that, make sure to run the test suite before every commit. Furthermore, use
git pushwithout any parameters for consecutive commits.
Open a Pull request (PR)
Navigate to pmeier/pystiche/pulls on GitHub and click on the green button “New pull request”.
Click on “compare across forks” below the “Compare changes” headline.
Select your fork for “head repository” and your branch for “compare” in the drop-down menus.
Click the the green button “Create pull request”.
If the time between the branch being pushed and the PR being opened is not too long, GitHub will offer you a yellow box after step 1. If you click the button, you can skip steps 2. and 3.
Steps 1. to 3. only have to performed once. If you want to continue contributing,
make sure to branch from the current
master branch. You can use
$ git checkout master $ git pull origin $ git checkout -b "my-second-awesome-feature-or-bug-fix"
If you forgot to do that or if since the creation of your branch many commits have
been made to the
master branch, simply rebase your branch on top of it.
$ git checkout master $ git pull origin $ git checkout "my-second-awesome-feature-or-bug-fix" $ git rebase master
If you are contributing bug-fixes or documentation improvements, you can open a pull request (PR) without further discussion. If on the other hand you are planning to contribute new features, please open an issue and discuss the feature with us first.
Every PR is subjected to multiple automatic checks (continuous integration, CI) as well as a manual code review that it has to pass before it can be merged. The automatic checks are performed by tox. You can find details and instructions how to run the checks locally below.
Code format and linting¶
cd $PYSTICHE_ROOT source .venv/bin/activate tox -e lint-style
flake8 are run by
pre-commit before every commit.
cd $PYSTICHE_ROOT source .venv/bin/activate tox -e lint-typing
For convenience, you can run all lint checks with
cd $PYSTICHE_ROOT source .venv/bin/activate tox -f lint
pystiche uses pytest to run the test suite.
You can run it locally with
cd $PYSTICHE_ROOT source .venv/bin/activate tox
pystiche_papers adds the following custom options with the
Options prefixed with
--skip are run by default and skipped if the option is
given. Options prefixed with
--run are skipped by default and run if the option
These options are passed through
tox if given after a
-- flag. For example,
the CI invokes the test suite with
cd $PYSTICHE_ROOT source .venv/bin/activate tox -- --skip-large-download
To build the html documentation locally, run
cd $PYSTICHE_ROOT source .venv/bin/activate tox -e docs-html
To build the latex (PDF) documentation locally, run
cd $PYSTICHE_ROOT source .venv/bin/activate tox -e docs-latex
To build both, run
cd $PYSTICHE_ROOT source .venv/bin/activate tox -f docs
Building the documentation triggers a
sphinx gallery build by
default for the example galleries. This which will take some time to complete. To get
pystiche offers two environment variables:
False, the code inside the galleries is not executed. See the official sphinx-gallery documentation for details. Defaults to
True, downloads pre-built galleries and uses them instead of rebuilding. For the
masterthe galleries are at most six hours old. Defaults to
Both environment variables are evaluated with