From b562d92aa11d5cc90ad367ae78961829587469fe Mon Sep 17 00:00:00 2001
From: Khabib <136262760+Khabib73@users.noreply.github.com>
Date: Thu, 8 Oct 2026 16:43:46 +0300
Subject: [PATCH 1/3] Add Makefile

---
 CONTRIBUTING.md | 80 ++++++++++++++++++++++++++++++++++++++++++++-----
 Makefile        | 45 ++++++++++++++++++++++++++++
 2 files changed, 118 insertions(+), 7 deletions(-)
 create mode 100644 Makefile

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 796142584..e9fc43d2d 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -40,10 +40,31 @@ poetry install --extras compatible-mypy
 To activate your `virtualenv` run `eval $(poetry env activate)`.
 
 
+## Makefile
+
+To make local development easier, all common commands are available
+via the [`Makefile`](Makefile). Run `make help` to see all available targets:
+
+```bash
+make help
+```
+
+Main targets:
+
+- `make format` — format and autofix code with `ruff`
+- `make lint` — run all linting checks (`ruff` and `flake8`)
+- `make type-check` — run `mypy` type checks
+- `make unit` — run standard tests with `pytest`
+- `make typesafety` — run type-safety tests (`pytest-mypy-plugins`)
+- `make slots` — check `__slots__` correctness with `slotscheck`
+- `make package` — check package dependencies with `pip check`
+- `make test` — run all checks: lint, type-check, unit tests, slots, and package
+
+
 ## Tests
 
 We use `pytest` and `flake8` for quality control.
-We also use `wemake_python_styleguide` to enforce code quality.
+We also use `wemake_python_styleguide` and `ruff` to enforce code quality.
 
 To run standard tests:
 
@@ -51,18 +72,51 @@ To run standard tests:
 poetry run pytest returns docs/pages tests
 ```
 
+Or simply:
+
+```bash
+make unit
+```
+
 **NOTE:** type-safety tests not included, see section on type tests below
 
 To run linting:
 
 ```bash
 poetry run flake8 .
+poetry run ruff check --exit-non-zero-on-fix
+poetry run ruff format --check --diff
 ```
+
+Or simply:
+
+```bash
+make lint
+```
+
 Keep in mind: default virtual environment folder excluded by flake8 style checking is `.venv`.
 If you want to customize this parameter, you should do this in `setup.cfg`.
 
 These steps are mandatory during CI.
 
+### Pre-commit hooks
+
+We use [`pre-commit`](https://pre-commit.com/) to run some checks
+automatically before each commit. Among others, it runs `ruff check`
+and `ruff format` on the changed files.
+
+To install the hooks, run:
+
+```bash
+poetry run pre-commit install
+```
+
+To run all hooks manually:
+
+```bash
+poetry run pre-commit run --all-files
+```
+
 ### Type tests
 
 We also use `pytest-mypy-plugins`. Tests cases are located inside `./typesafety`
@@ -74,6 +128,12 @@ The type-safety tests can be run with the following:
 poetry run pytest typesafety
 ```
 
+Or simply:
+
+```bash
+make typesafety
+```
+
 **NOTE:** This can take upwards of 20 minutes, only recommended to run if necessary.
 
 Here's [a helpful tutorial](https://sobolevn.me/2019/08/testing-mypy-types) if you are looking
@@ -86,7 +146,14 @@ We use `mypy` to run type checks on our code.
 To use it:
 
 ```bash
-poetry run mypy returns tests/**/*.py
+poetry run mypy returns
+poetry run mypy docs tests
+```
+
+Or simply:
+
+```bash
+make type-check
 ```
 
 This step is mandatory during CI.
@@ -116,15 +183,14 @@ In this method, the latest version of the app is always in the `master` branch.
 
 Before submitting your code please do the following steps:
 
-1. Run `pytest` to make sure everything was working before
+1. Run `make unit` (or `pytest`) to make sure everything was working before
 2. Add any changes you want
 3. Add tests for the new changes
 4. Edit documentation if you have changed something significant
 5. Update `CHANGELOG.md` with a quick summary of your changes
-6. Run `pytest` again to make sure it is still working
-7. Run `mypy` to ensure that types are correct
-8. Run `flake8` to ensure that style is correct
-9. Run `slotscheck` to ensure that slots are correct
+6. Run `make format` to format the code with `ruff`
+7. Run `make test` to run all checks: linting (`ruff`, `flake8`),
+   `mypy` types, `pytest` tests, `slotscheck`, and `pip check`
 
 
 ## Other help
diff --git a/Makefile b/Makefile
new file mode 100644
index 000000000..3ddb28861
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,45 @@
+SHELL := /usr/bin/env bash
+POETRY ?= poetry
+.DEFAULT_GOAL := help
+
+.PHONY: help
+help: ## Show the help message
+	@echo 'Usage: make [target]'
+	@echo ''
+	@echo 'Available targets:'
+	@awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z_-]+:.*?## / {printf "  %-20s %s\n", $$1, $$2}' $(MAKEFILE_LIST)
+
+.PHONY: format
+format: ## Format code with ruff
+	$(POETRY) run ruff check --fix
+	$(POETRY) run ruff format
+
+.PHONY: lint
+lint: ## Run linting checks (ruff, flake8)
+	$(POETRY) run ruff check --exit-non-zero-on-fix
+	$(POETRY) run ruff format --check --diff
+	$(POETRY) run flake8 .
+
+.PHONY: type-check
+type-check: ## Run type checking (mypy)
+	$(POETRY) run mypy returns
+	$(POETRY) run mypy docs tests
+
+.PHONY: unit
+unit: ## Run unit tests with pytest
+	$(POETRY) run pytest returns docs/pages tests
+
+.PHONY: typesafety
+typesafety: ## Run type-safety tests with pytest-mypy-plugins
+	$(POETRY) run pytest typesafety -p no:cov -o addopts=""
+
+.PHONY: slots
+slots: ## Check __slots__ correctness with slotscheck
+	$(POETRY) run python -m slotscheck returns --verbose
+
+.PHONY: package
+package: ## Check package dependencies with pip
+	$(POETRY) run pip check
+
+.PHONY: test
+test: lint type-check unit slots package ## Run all checks (lint, type-check, unit, slots, package)

From ab45c45215494503977905973edfe3d7d75b0414 Mon Sep 17 00:00:00 2001
From: Khabib <136262760+Khabib73@users.noreply.github.com>
Date: Thu, 8 Oct 2026 17:08:57 +0300
Subject: [PATCH 2/3] Update CI

---
 .github/workflows/test.yml | 16 +++++-----------
 Makefile                   |  2 +-
 2 files changed, 6 insertions(+), 12 deletions(-)

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index e753fdfd1..c54c28b23 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -48,20 +48,14 @@ jobs:
 
     - name: Run tests
       run: |
-        poetry run flake8 .
-
-        # In order to make `exclude` option work, we need to separate the checks
-        # of returns and its tests into two separated commands
-        poetry run mypy --enable-error-code=unused-awaitable returns
-        poetry run mypy docs tests
+        make lint
+        make type-check
 
         # Different python versions are covered differently:
-        poetry run pytest returns docs/pages tests
+        make unit
 
-        # TODO: re-enable after all problems are fixed
-        # poetry run poetry check
-        poetry run pip check
-        poetry run python -m slotscheck returns --verbose
+        make slots
+        make package
 
     - name: Upload coverage to Codecov
       if: matrix.python-version == 3.11
diff --git a/Makefile b/Makefile
index 3ddb28861..6b93f085a 100644
--- a/Makefile
+++ b/Makefile
@@ -22,7 +22,7 @@ lint: ## Run linting checks (ruff, flake8)
 
 .PHONY: type-check
 type-check: ## Run type checking (mypy)
-	$(POETRY) run mypy returns
+	$(POETRY) run mypy --enable-error-code=unused-awaitable returns
 	$(POETRY) run mypy docs tests
 
 .PHONY: unit

From e1fe25d42c8220bc07af3a356d5fdb67d13a1133 Mon Sep 17 00:00:00 2001
From: Khabib <136262760+Khabib73@users.noreply.github.com>
Date: Thu, 8 Oct 2026 17:34:14 +0300
Subject: [PATCH 3/3] Update typesafety

---
 .github/workflows/test.yml | 5 ++---
 Makefile                   | 5 +++--
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index c54c28b23..a3fc064f6 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -97,6 +97,5 @@ jobs:
 
     - name: Run typesafety tests
       run: |
-        poetry run pytest typesafety \
-          --num-shards=4 --shard-id=${{ matrix.shard }} \
-          -p no:cov -o addopts="" --mypy-ini-file=setup.cfg
+        make typesafety \
+          PYTEST_EXTRA_ARGS="--num-shards=4 --shard-id=${{ matrix.shard }}"
diff --git a/Makefile b/Makefile
index 6b93f085a..5ff5aa8ff 100644
--- a/Makefile
+++ b/Makefile
@@ -30,8 +30,9 @@ unit: ## Run unit tests with pytest
 	$(POETRY) run pytest returns docs/pages tests
 
 .PHONY: typesafety
-typesafety: ## Run type-safety tests with pytest-mypy-plugins
-	$(POETRY) run pytest typesafety -p no:cov -o addopts=""
+typesafety: ## Run type-safety tests with pytest-mypy-plugins (PYTEST_EXTRA_ARGS for sharding, etc)
+	$(POETRY) run pytest typesafety $(PYTEST_EXTRA_ARGS) \
+	  -p no:cov -o addopts="" --mypy-ini-file=setup.cfg
 
 .PHONY: slots
 slots: ## Check __slots__ correctness with slotscheck