## 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](https://gist.github.com/seunggabi/87f8c722d35cd07deb3f649d45a31082).

### Commit message rules

We ask that you adhere to the following
[commit message format](https://gist.github.com/joshbuchea/6f47e86d2510bce28f8e7f42ae84c716).

## 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.
```bash
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
```bash
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
```bash
poetry update
```

### Documentation
Assuming you use [reStructuredText (reST) format docstrings](https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html)
to annotate your modules and objects. You can easily build the Sphinx documentation for your module 
by activating the virtual environment and then running

```bash
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](https://github.com/psf/black). 
To format your code, run

```bash
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
```bash
poetry run poe test_no_cov
```
To execute all tests, including integration with DBs and APIs tests, run
```bash
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
```bash
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
```bash
poetry run poe lint
```
And if it doesn't, to automatically fix whatever is possible with `black`, run
```bash
poetry run poe format
```

Tests are configured via [`.env_file`](.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

```bash
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

```bash
docker compose --profile stats up
```

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

To launch both groups run
```bash
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`:

```bash
poetry run poe info
```
