Contributing

Contributions to project “Sailor” are warmly welcomed. This page gives you detailed information on steps to take when you want to:

Report a bug

You can report a bug by creating an issue in the project repository. Ideally your report should include:

  • short self-contained example or code snippet how to reproduce the bug

  • description of the current behaviour and what is wrong with it

  • description of the desired behavior, depicting how the code is expected to work

Create a feature request

You can request a feature by creating an issue in the project repository. Alternatively you can get in touch with the developers directly by reaching out to project.sailor@sap.com

Contributing to the code base

Getting started

This section will give you the minimum requirements to starting development with project “Sailor”.

Prerequisites

You have cloned the Github project. Every instruction assumes that you are currently in the project folder on your development machine.

Ideally you have created a dedicated python environment for development with “Sailor”. Please check the classifiers in setup.py for the currently supported python versions and use the most recent eligible version.

Installation

Install the dependencies by running:

pip install -r requirements.txt

Install the “Sailor” sources

pip install -e .

Additional tooling

This section describes how we support additonal use cases that may occur during development.

Dev tools

Install tools required for everything related to Sailor development by running:

pip install -r .ci/requirements_dev.txt

Find the current settings and/or possible instructions to run linting/testing tools in setup.cfg.

Requirements management

requirements.txt lists the concrete dependencies that our code is meant to be tested for. This file should never be modified manually, only through pip-compile (see below).

requirements.in lists abstract dependencies. If you would like to introduce a new package as dependency to this project:

  1. please add it to requirements.in and run pip-compile to update the requirements.txt

  2. Add the resulting changes to your next pull request.

pip-compile is part of package pip-tools (can be installed via pip).

Building the package

We are using a PEP517 and PEP518 compliant build tooling.

To create distribution files simply run:

python -m build -ws

Contributing to the documentation

Sphinx is used to build the documentation. All documentation files are written in reStructuredText and can be found in the docs folder.

Requirements

You will need to install Sphinx and dependencies that we use. If you have installed all dev tools already, you can skip this step.

pip install -r .ci/docs/requirements_docs.txt

Build

Go to the docs directory and run:

make html

The HTML is built into the docs/_build directory. You can view the docs by simply opening index.html with your browser.

If you just ran make html for the first time, it might be that the documentation is not rendered properly (specifically the TOC for the API documentation on the left). In this case please run once:

touch apidoc.rst
make html SPHINXOPTS="-a"

Further builds should only require make html.

Adding or removing API doc pages

This step is only required when new modules/packages have been added or removed. If you want to update the apidoc:

  1. run: make apidoc

  2. (only if any packages/modules have been removed): delete the corresponding .rst files

  3. commit the changes