# Contributor guidelines

## Developer prerequisites

### pre-commit

Refer to [pre-commit](https://pre-commit.com/#installation) for installation instructions.

TL;DR:

```sh
curl -LsSf https://astral.sh/uv/install.sh | sh  # Install uv
uv tool install pre-commit  # Install pre-commit
pre-commit install  # Install pre-commit hooks
```

Installing [pre-commit](https://pre-commit.com/#installation) will ensure you adhere to the project code quality
standards.

## Code standards

[ruff](https://beta.ruff.rs/docs/) and [doc8](https://doc8.readthedocs.io/) will be automatically triggered by [pre-commit](https://pre-commit.com/#installation).

[ruff](https://beta.ruff.rs/docs/) is configured to do the job of [black](https://black.readthedocs.io/) and [isort](https://pycqa.github.io/isort/) as well.

Still, if you want to run checks manually:

```sh
make doc8
make ruff
```

## Requirements

Requirements are compiled using [uv](https://docs.astral.sh/uv/).

```sh
make compile-requirements
```

## Virtual environment

You are advised to work in virtual environment.

TL;DR:

```sh
python -m venv env
pip install -e .[all]
```

## Documentation

Check the [documentation](https://fakepy.readthedocs.io/#writing-documentation).

## Testing

Check [testing](https://fakepy.readthedocs.io/#testing).

If you introduce changes or fixes, make sure to test them locally using
all supported environments. For that use [tox](https://tox.wiki).

```sh
tox
```

In any case, GitHub Actions will catch potential errors, but using tox speeds
things up.

For a quick test of the package and all examples, use the following Makefile
command:

```sh
make test-all
```

## Releasing

**Sequence of steps:**

1. Clean and build
   > ```sh
   > make clean
   > make build
   > ```
2. Check the build
   > ```sh
   > make check-build
   > ```
3. Test release on test.pypi.org. Make sure to check it before moving forward.
   > ```sh
   > make test-release
   > ```
4. Release
   > ```sh
   > make release
   > ```

## Pull requests

You can contribute to the project by making a [pull request](https://github.com/barseghyanartur/fake.py/pulls).

For example:

- To fix documentation typos.
- To improve documentation (for instance, to add new recipe or fix
  an existing recipe that doesn’t seem to work).
- To introduce a new feature (for instance, add support for a non-supported
  file type).

**Good to know:**

- This library consists of a single `fake.py` module. That module is
  dependency free, self-contained (includes all tests) and portable.
  Do not submit pull requests splitting the `fake.py` module into small
  parts. Pull requests with external dependencies in `fake.py` module will
  not be accepted either.
- Some tests contain simplified implementation of existing libraries (Django
  ORM, TortoiseORM, SQLAlchemy). If you need to add integration tests for
  existing functionality, you can add the relevant code and requirements
  to the examples, along with tests. Currently, all integration tests
  are running in the CI against the latest version of Python.

**General list to go through:**

- Does your change require documentation update?
- Does your change require update to tests?
- Does your change rely on third-party package or a cloud based service?
  If so, please consider turning it into a dedicated standalone package,
  since this library is dependency free (and will always stay so).

**When fixing bugs (in addition to the general list):**

- Make sure to add regression tests.

**When adding a new feature (in addition to the general list):**

- Make sure to update the documentation (check whether the [installation](https://fakepy.readthedocs.io/#installation),
  [features](https://fakepy.readthedocs.io/#features), [recipes](https://fakepy.readthedocs.io/en/latest/recipes.html) and [quick start](https://fakepy.readthedocs.io/en/latest/quick_start.html) require changes).

## GitHub Actions

Only non-EOL versions of Python and software [fake.py](https://fakepy.readthedocs.io) aims to integrate with
are supported.

On GitHub Actions includes tests for more than 40 different variations of
Python versions and integration packages. Future, non-stable versions
of Python are being tested too, so that new features/incompatibilities
could be seen and adopted early.

For the list of Python versions supported by GitHub, see GitHub Actions
[versions manifest](https://github.com/actions/python-versions/blob/main/versions-manifest.json).

## Questions

Questions can be asked on GitHub [discussions](https://github.com/barseghyanartur/fake.py/discussions).

## Issues

For reporting a bug or filing a feature request, use GitHub [issues](https://github.com/barseghyanartur/fake.py/issues).

**Do not report security issues on GitHub**. Check the [support](https://fakepy.readthedocs.io/#support) section.