Skip to content

How to Contribute

We welcome collaborators who would like to help expand and improve Bookops-Worldcat. Here are some ways to contribute.

Report bugs or suggest enhancements

Please use our Github issue tracker to submit bug reports or request new features.

Contribute code or documentation

Info

This page contains a draft of our contribution guidelines but there is still more for us to add.

TO DO:

  • Add style guide for documentation
    • docstring style conventions
    • type hints
    • how to build docs after making edits
  • Add CI/CD info

Style and Requirements

For new code contributions, please use the tools and standards in place for Bookops-Worldcat:

  • Code style:
  • Dependency management and package publishing with Poetry
  • Documentation written in Markdown using MkDocs and plugins
  • Tests written with pytest
Tip

If you use VS Code there are certain extensions which will automate code formatting and support some of our code style requirements which may make your work easier while contributing to Bookops-Worldcat. Similar extensions are available on other IDEs. Those extensions include:

Additions to add to your settings.json file:

settings.json for VS Code
{
    "editor.defaultFormatter": "ms-python.black-formatter",
    "editor.formatOnSave": true,
    "flake8.args": [
        "--max-line-length=88",
    ],
}

Install and Setup

To get started contributing code to Bookops-Worldcat you will need:

  • Python 3.8 or newer
  • git
  • poetry
Install Poetry

Bookops-Worldcat uses poetry to manage virtual environments, dependencies, and publishing workflows. We use pipx to run poetry (if you don't have pipx, see the installation instructions). For other installation options, see the poetry documentation.

Fork the repo

Fork the repository in GitHub and clone your fork locally 

git clone https://github.com/<your username>/bookops-worldcat
cd bookops-worldcat

Create a new branch for your changes
git checkout -b new-branch
Create a virtual environment and install dependencies

Poetry will create a virtual environment, read the pyproject.toml and poetry.lock files, resolve dependencies, and install them with one command. 

poetry install

Run tests

Run tests before making changes on your fork.

Info

Our live tests are designed to look for API credentials in a specific file/directory in a Windows environment. We will need to refactor the live tests to allow contributors to run live tests with their own API credentials and run live tests in a macOS environment.

# basic usage without webtests
python -m pytest "not webtest"
# with test coverage and without webtests
python -m pytest "not webtest" --cov=bookops_worldcat/