Skip to content

Latest commit

 

History

History
168 lines (124 loc) · 6.13 KB

CONTRIBUTING.md

File metadata and controls

168 lines (124 loc) · 6.13 KB
Raw

Introduction

We will be glad to receive your pull requests (PRs) and issues for adding new features if you are missing something. We always look forward to your contributions to Chatsky.

Rules for submitting a PR

All PRs are reviewed by Chatsky developers team. In order to make the job of reviewing easier and increase the chance that your PR will be accepted, please add a short description with information about why this PR is needed and what changes will be made. Please use the following rules to write the names of branches and commit messages.

Rules for writing names of branches

We hope that you adhere to the following format.

Commit message rules

We ask that you adhere to the following commit message format.

Managing your workflow

We use poetry and poethepoet as handy automation tools, which reads pyproject.toml to get specification for commands. poetry is a tool for command running automatization. Usage signature of the poetry is poetry run poe COMMAND. If your environment does not support poetry, it can be installed as a regular python package with pip install poetry. poethepoet will be automatically installed upon installation of devel dependency group.

Platforms

We suggest using a linux-based platform for addon development. While the repository can be cloned to any platforms that can run python, the docker functionality will not be available for Windows out of the box.

Virtual Environment

The most essential part is setting up the virtual environment. poetry automatically creates and manages it upon any command execution. By default, it will try using current virtual environment if there is any in the current directory or it will create a new one. You can display information about the current environment using poetry env info command. You can also switch to system-wide python environment with poetry env use system command.

The following command creates a virtual environment dir and installs all the dependencies, which are required for development.

poetry install --with lint,test,devel,tutorials,docs --all-extras

The environment will be activated automatically.

If you want to delete all the virtual environments, run

poetry env remove --all

Updating Dependencies

We use poetry.lock to ensure that all builds with the same lock file have the same 3rd-party library versions. This lets us know whether workflow fails due to our part or because a dependency update breaks something.

In order to update versions specified in poetry.lock, run

poetry update

Documentation

Assuming you use reStructuredText (reST) format docstrings to annotate your modules and objects. You can easily build the Sphinx documentation for your module by activating the virtual environment and then running

poetry run poe docs

Note that you'll need pandoc installed on your system in order to build docs.

After that docs/build dir will be created and you can open index file docs/build/index.html in your browser of choice.

Documentation links

In your tutorials, you can use special expanding directives in markdown cells. They can help shorten the comments and avoid boilerplate code. The documentation links generated by the directives are always relative to the local documentation and verified during build.

  • %pip install {args} This directive generates dependency installation cell, adds a comment and sets up "quiet" flag.

    It should be used in tutorials, like this: # %pip install chatsky[...].

  • %doclink({args}) This directive generates a documentation link. It supports 2 or three arguments and the generated link will look like: ARG1/ARG2#ARG3.

    The first argument can be either api for Chatsky codebase, tutorial for tutorials or guide for user guides.

  • %mddoclink({args}) This directive is a shortcut for %doclink that generates a markdown format link instead.

    The generated link will be either [ARG2](%doclink(ARG1,ARG2)) or [ARG3](%doclink(ARG1,ARG2,ARG3)).

Style

For style supporting we propose black, which is a PEP 8 compliant opinionated formatter. It doesn't take previous formatting into account. See more about black. To format your code, run

poetry run poe format

Test

We use black, mypy, flake8 as code style checkers and pytest as unit-test runner. To run unit-tests only, use

poetry run poe test_no_cov

To execute all tests, including integration with DBs and APIs tests, run

poetry run poe test_all

for successful execution of this command Docker and docker compose are required.

To do a quick sanity check without the need to up docker containers or wait for long tests, run

poetry run poe quick_test

There's also quick_test_coverage for quick htmlcov generation, though it is very likely to be incomplete due to deselection of some tests.

To make sure that the code satisfies only the style requirements, run

poetry run poe lint

And if it doesn't, to automatically fix whatever is possible with black, run

poetry run poe format

Tests are configured via .env_file.

Docker

Chatsky uses docker images for two purposes:

  1. Database images for integration testing.
  2. Images for statistics collection.

The first group can be launched via

docker compose --profile context_storage up

This will download and run all the databases (mysql, postgres, redis, mongo, ydb).

The second group can be launched via

docker compose --profile stats up

This will download and launch Superset Dashboard, Clickhouse, OpenTelemetry Collector.

To launch both groups run

docker compose --profile context_storage --profile stats up

This will be done automatically when running poetry run poe test_all.

Other provided features

You can get more info about poetry commands by info:

poetry run poe info