How to contribute to reader

Thank you for considering contributing to reader!

Reporting issues

Please report issues via GitHub Issues.

Include the following information:

  • Describe what you expected to happen.

  • If possible, include a minimal reproducible example to help identify the issue. This also helps check that the issue is not with your own code.

  • Describe what actually happened. Include the full traceback if there was an exception.

  • List your Python and reader versions. If possible, check if this issue is already fixed in the latest release or the latest code in the repository.


Please use Github Discussions for support or general questions.

Submitting patches

If there is no open issue for what you want to submit, prefer opening one for discussion before working on a pull request.

You can work on any help wanted issue that does not have an open PR or an assigned maintainer (no need to ask).

For other open issues, please ask first, there may be background that didn’t end up in the issue yet; also see Roadmap and Design notes.

Include the following in your patch:

  • Use Black to format your code. This and other tools will run automatically if you install pre-commit using the instructions below.

  • Include tests if your patch adds or changes code. Make sure the test fails without your patch.

  • Update any relevant documentation pages and docstrings; also see Documentation. Documentation pages and docstrings should be wrapped at 72 characters.

  • Add an entry in CHANGES.rst. Use the same style as other entries. Also include .. versionchanged:: inline changelogs in relevant docstrings.

First time setup

  • Make sure you have a GitHub account.

  • Download and install the latest version of git.

  • Configure git with your username and email.

    $ git config --global 'your name'
    $ git config --global 'your email'
  • Fork reader to your GitHub account by clicking the Fork button.

  • Clone your fork locally, replacing your-username in the command below with your actual username.

    $ git clone
    $ cd reader
  • Create a virtualenv. Use the latest version of Python.

    • Linux/macOS

      $ python3 -m venv .venv
      $ . .venv/bin/activate
    • Windows

      > py -3 -m venv .venv
      > .venv\Scripts\activate
  • Install reader in editable mode, with development dependencies.

    $ pip install -e '.[dev]'
  • Install the pre-commit hooks.

    $ pre-commit install --install-hooks
  • Alternatively, use to do the last two steps.

    $ ./ install-dev

Start coding

  • Create a branch to identify the issue you would like to work on. Branch off of the “master” branch.

    $ git fetch origin
    $ git checkout -b your-branch-name origin/master
  • Using your favorite editor, make your changes, committing as you go.

  • Include tests that cover any code changes you make. Make sure the test fails without your patch. Run the tests as described below.

  • Push your commits to your fork on GitHub and create a pull request. Link to the issue being addressed with fixes #123 in the pull request description.

    $ git push --set-upstream origin your-branch-name

Running the tests

Run the basic test suite with pytest.

$ pytest --runslow

This runs the tests for the current environment, which is usually sufficient. CI will run the full suite when you submit your pull request. You can run the full test suite with tox if you don’t want to wait.

$ tox

Running test coverage

Generating a report of lines that do not have test coverage can indicate what code needs to be tested. Use to run pytest using coverage, generate a report, and check required coverage.

$ ./ coverage-all

Open htmlcov/index.html in your browser to explore the report.

The library must have 100% test coverage; the unstable plugins, CLI, and web app do not have coverage requirements.

Read more about coverage.

Type checking

Run type checking with mypy.

$ mypy --strict src

The library must pass strict type checking; the plugins, CLI, and web app do not have type checking requirements.

Read more about mypy.

Building the docs

Build the docs using Sphinx.

$ make -C docs html

Open docs/_build/html/index.html in your browser to view the docs.

Read more about Sphinx.

$ ./ command [argument ...]

The script wraps the steps above as “executable documentation”.

./ install-dev

First time setup (install reader and pre-commit hooks)

./ test / ./ test-all

Running the tests

./ coverage-all

Running test coverage

./ typing

Type checking

./ docs

Building the docs

Arguments are usually passed along to the underlying tool, e.g. typing arguments are passed to pytest; see the script source for details.

If you have entr installed, test-dev, typing-dev, and docs-dev will run the corresponding commands when the files in the repo change.

Likewise, serve-dev will run the web app with the Flask development server.