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.

1. Fork pystiche on GitHub

Navigate to pmeier/pystiche on GitHub and click the Fork button in the top right corner.

2. Clone your fork to your local file system

Use git clone to get a local copy of pystiche s repository that you can work on:

$ PYSTICHE_ROOT="pystiche"
$ git clone "https://github.com/pmeier/pystiche.git" $PYSTICHE_ROOT

3. Setup your development environment

$ cd $PYSTICHE_ROOT
$ virtualenv .venv --prompt="(pystiche) "
$ source .venv/bin/activate
$ pip install -r requirements-dev.txt
$ pre-commit install

Note

While pystiche s 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 virtualenv installed, you can do so by running pip install --user virtualenv.

4. Create a branch for local development

Use git checkout to 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!

5. Use tox to run various checks

$ tox

Note

Running tox is 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.

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

Note

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 push without any parameters for consecutive commits.

7. Open a Pull request (PR)

1. Navigate to pmeier/pystiche/pulls on GitHub and click on the green button "New pull request".
2. Click on "compare across forks" below the "Compare changes" headline.
3. Select your fork for "head repository" and your branch for "compare" in the drop-down menus.
4. Click the the green button "Create pull request".

Note

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.

$ git checkout master
$ git pull origin
$ git checkout -b "my-second-awesome-feature-or-bug-fix"

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

pystiche uses isort to sort the imports, black to format the code, and flake8 to enforce PEP8 compliance. To format and check the code style, run

cd $PYSTICHE_ROOT
source .venv/bin/activate
tox -e lint-style

Furthermore, pystiche_papers is PEP561 compliant and checks the type annotations with mypy. To check the static typing, run

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

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