CONTRIBUTING.rst

Guidelines for Contributing

PyPika welcomes contributions in all forms. These may be bugs, feature requests, documentation, or examples. Please feel free to:

1. Submitting an issue
2. Opening a pull request
3. Helping with outstanding issues and pull requests

Open an issue

If you find a bug or have a feature request, please open an issue on GitHub. Please just check that the issue doesn't already exist before opening a new one.

Local development steps

Create a forked branch of the repo

Do this once but keep it up to date

1. Fork the kayak/PyPika repo GitHub

2. Clone forked repo and set upstream

   git clone git@github.com:<your-username>/pypika.git
   cd pypika
   git remote add upstream git@github.com:kayak/pypika.git

Setup local development environment

1. Setup up python virtual environment

   Create and activate the environment. Here is an example using venv from the standard library:

   python -m venv .venv
   source .venv/bin/activate

2. Install python dependencies for development

   With the virtual environment activated, install the development requirements, pre-commit, and the package itself:

   make install

3. Run the tests

   The unit tests are run with unittest via tox. To run the tests locally:

   make test

   These tests will also run on GitHub Actions when you open a pull request.

4. Build the docs locally

   Our docs are built with Sphinx. To build the docs locally:

   make docs.build

   Open the docs in your browser. For instance, on macOS:

   open docs/_build/index.html

Pull Request checklist

Please check that your pull request meets the following criteria:

• Unit tests pass
• pre-commit hooks pass
• Docstring and examples and checking for correct render in the docs

Documentation

Documentation is built with Sphinx and hosted on Read the Docs. The latest builds are displayed on their site here.

The code documentation is to be written in the docstrings of the code itself or in the various .rst files in project root or the docs/ directory.

The docstrings can be in either Numpy or Sphinx format.

Automations

We use pre-commit to automate format checks. Install the pre-commit hooks with the make install command described above.

GitHub Actions runs both format checks and unit tests on every pull request.

NOTE: The hosted documentation is built separately from the GitHub Actions workflow. To build the docs locally, use the make docs.build command described above.