pytest-csv-params/docs/pages/developer.md

# Developer Guide

If you want to develop for / with the Pytest CSV Params Plugin, consider to clone the repository:

```bash
git clone https://git.codebau.dev/pytest-plugins/pytest-csv-params.git
```

You need **Python 3.8** or newer. 

The project's dependencies and building are managed by `poetry`. Please follow the instructions from
[python-poetry.org](https://python-poetry.org/) to install `poetry` on your system.

Install all the dependencies, including the development dependencies:

```bash
poetry install
```

## Commit Signing

Commit signing is mandatory for all commits for the `main` branch. Please make sure, your public key is set up and
registered with `git.codebau.dev`.

## Testing

Tests are implemented with `pytest`. You find them in the `tests` folder. Besides unit and integration tests, some other
checks are executed by `pytest` plugins:

- **`pytest-black`:** This plugin checks code formatting with [`black`](https://github.com/psf/black). If tests fail,
  try `poetry run black .` from the project root to fix formatting issues. Configuration: `pyproject.toml`, section
  `[tool.black]`.
- **`pytest-isort`:** This plugin checks import sorting with [`isort`](https://github.com/PyCQA/isort). If tests fail,
  try `poetry run isort .` from the project root to fix import sorting issues. Configuration: `pyproject.toml`, section
  `[tool.isort]`.
- **`pytest-pylint`:** This plugin does a static code analysis with [`pylint`](https://github.com/PyCQA/pylint). The
  test configuration can be found in `.pylintrc` in the project root.
- **`pytest-bandit`:** This plugin performs a static security analysis of the code with
  [`bandit`](https://github.com/PyCQA/bandit). The configuration is part of the `[tool.pytest.ini_options]` section in
  the `pyproject.toml`, config keys `bandit_*`.
- **`pytest-mypy`:** This plugin uses [`mypy`](https://mypy.readthedocs.io/en/stable/) to perform typing checks against
  the code. The configuration can be found in the `pyproject.toml`, section `[tool.mypy]`.

Most plugins are enabled by the `addopts` switches, configured in the `pyproject.toml`, section
`[tool.pytest.ini_options]`. Some plugins have extra configuration switches even there.

Additionally, the code coverage is measured by `pytest-cov` using [`coverage.py`](https://github.com/nedbat/coveragepy).
A high coverage alone is not a very good metric, but it helps to find and fix coverage weaknesses. The configuration for
coverage measurement is in the `pyproject.toml`, sections `[tool.coverage]`, `[tool.coverage.run]` and
`[tool.coverage.report]`.

There are some other pytest plugins installed and used for tests:

- **`pytest-mock`:** Simplified mocking
- **`pytest-clarity`:** Better output of assertion errors
- **`pytest-order`:** Execute tests in a given order (used in {mod}`tests.poc.test_parametrize_with_generator`).

### Test runs with `pytest`

Just run all the tests with:

```bash
poetry run pytest
```

### Test runs with `tox`

`tox` is used to execute all tests under the different supported Python versions. Make sure you installed all relevant
versions on your system, for example with [`pyenv`](https://github.com/pyenv/pyenv).

To execute them all, run:

```bash
poetry run tox
```

If you experience strange `tox` errors, try to recreate the `tox` environments:

```bash
poetry run tox -r
```

`tox` is configured in the `pyproject.toml`, section `[tool.tox]`.

```{admonition} No new or changed code without test
If you add or change code, please make sure your changes are covered by meaningful tests.
```

## Building

There are two different things to build from the source code: The **Wheel distribution package** from the Python code 
and the **documentation**.

### Code

The building and deployment is managed by `poetry`. The complete build and deploy configuration takes place in the
`pyproject.toml`. Besides the standard configuration in section `[tool.poetry]`, additional URLs are defined in section
`[tool.poetry.urls]`. As a speciality for this plugin, an entry point is defined in section
`[tool.poetry.plugins."pytest11"]`.

To build the packages, just run `poetry build` from the project root.

(build-docs)=
### Docs

The docs are in the `docs` folder. There is a `conf.py` that contains all the settings. Documentation is managed by
[`sphinx`](https://www.sphinx-doc.org/). There is a `make` file (`Makefile`) as well as a `make.bat`, they contain some
configuration also.

The `serve.py` scripts starts a live reload server to preview the documentation.

To build the documentation, run `poetry run make html` (respectively `poetry run make.bat html` on Windows) from the
`docs` directory.

## Publishing

```{warning}
The following section is more a reference for project members. If you not belong to the project, you'll not be able to
publish or update packages.

Maybe you find it helpful as a boiler plate for your own projects.
```

### Increase Version

If not already done, increase the version in the `pyproject.toml`. This can be done manually, but `poetry` offers a
helper for that:

| `poetry` command       | Effect         |
|------------------------|----------------|
| `poetry version patch` | increase patch | 
| `poetry version minor` | increase minor |
| `poetry version major` | increase major |

### Complete Changelog

Update the `docs/pages/changelog.md` file with all relevant things happened since the last release. Set a compare link
and a link to the release page. You can set them up even if the release does not exist at the moment.

Don't forget to commit now!

### Tag the release

Set a git tag in the format `vX.Y.Z` (with the leading `v`). Push all your commits and the tag now. 

### PyPI

```{admonition} Poetry configuration for publishing
If not already done, you need to setup `poetry` for publishing.

**1. Configuration for production PyPI**

- Get your token from [pypi.org](https://pypi.org/)
- Set your token with `poetry config pypi-token.pypi pypi-YOUR_PROD_TOKEN`

**2. Configuration for test PyPI**

- Get your token from [test.pypi.org](https://test.pypi.org/)
- Setup the test repo: `poetry config repositories.test.url https://test.pypi.org/legacy/`
- Set your token with `poetry config pypi-token.test pypi-YOUR_TEST_TOKEN`

**3. Configuration for Codebau Package Repository**

- Get your token from [git.codebau.dev](https://git.codebau.dev/)
- Setup the codebau repo:
  `poetry config repositories.codebau.url https://git.codebau.dev/api/packages/pytest-plugins/pypi`
- Setup your token with `poetry config pypi-token.codebau YOUR_CODEBAU_TOKEN`
```

#### Publish to test.pypi.org

It's a good practice to publish a new package to [test.pypi.org](https://test.pypi.org/) first.

```bash
poetry publish --build -r test
```

You can omit the `--build` param when you already built the package.

#### Publish to production pypi.org

```bash
poetry publish --build
```

#### Publish to git.codebau.dev Package Repository

```bash
poetry publish --build -r codebau
```

### Documentation

The documentation is automatically build from the `main` branch and published to `docs.codebau.dev`. If you want to
build by yourself, see {ref}`Building / Docs <build-docs>`. You find the compiled docs under `dist/docs/html`.