Add manuals

README.md

@@ -2,6 +2,11 @@
 
 В рамках задания мы напишем на Python игрушечный бэкенд для интернет-магазина с локальным хранилищем данных в памяти: научимся создавать, читать, изменять и удалять товары, работать с корзиной и управлять всем этим через простую консоль администратора. Задание выполняется поэтапно, и каждый следующий шаг опирается на предыдущий.
 
+## Мануалы
+
+- [Запуск локальных проверок](manuals/local_checks.md) — как установить uv на macOS и Windows и запустить скрипты, которые локально выполняют те же проверки кода, что и CI на GitHub.
+- [Сдача домашнего задания](manuals/submit_homework.md) — как загрузить решение в свой форк, оформить Pull Request в исходный репозиторий и что нужно для того, чтобы работа была принята на проверку.
+
 ## Задания
 
 - [Часть 1. Генератор идентификаторов Twitter Snowflake](src/part1/TASK.md) — нужно написать генератор 64-битных числовых идентификаторов, в которые упакованы метка времени, номер узла и счётчик последовательности. Такие идентификаторы уникальны и примерно упорядочены по времени, а из самого идентификатора можно узнать, когда и на каком узле он был создан.

manuals/local_checks.md

@@ -0,0 +1,90 @@
+# Запуск локальных проверок
+
+Перед тем как открыть Pull Request, прогоните у себя те же проверки, что запускаются в CI на GitHub. Так вы найдёте ошибки заранее, не дожидаясь результата CI.
+
+## Что проверяется
+
+Скрипты устанавливают зависимости, затем проверяют код в папке `src`: линтером, форматированием и статическим анализатором типов. Если какая-то проверка не пройдена, скрипт останавливается с ошибкой.
+
+## Установка uv
+
+[uv](https://docs.astral.sh/uv/) — менеджер пакетов и окружений для Python. Проверки запускаются через него, поэтому вам потребуется его установить.
+
+### macOS
+
+Через официальный установщик:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+Или через Homebrew:
+
+```bash
+brew install uv
+```
+
+### Windows
+
+Через PowerShell:
+
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+Или через winget:
+
+```powershell
+winget install --id=astral-sh.uv -e
+```
+
+### Проверка установки
+
+Закройте и снова откройте терминал (иначе он не увидит обновлённый `PATH`), затем выполните:
+
+```bash
+uv --version
+```
+
+Если команда напечатала версию, всё готово. Другие способы установки описаны в [документации uv](https://docs.astral.sh/uv/getting-started/installation/).
+
+## Запуск проверок
+
+Скрипты лежат в корне репозитория. Их можно запускать из любой папки, они сами переходят в корень проекта. Если `uv` не установлен, скрипт напечатает сообщение об этом и завершится.
+
+### macOS / Linux
+
+```bash
+./run_local_checks
+```
+
+Если появилась ошибка `Permission denied`, сделайте скрипт исполняемым и запустите снова:
+
+```bash
+chmod +x run_local_checks
+./run_local_checks
+```
+
+### Windows
+
+В PowerShell или в командной строке (cmd):
+
+```powershell
+.\run_local_checks.bat
+```
+
+Если у вас установлен Git Bash, можно запустить и bash-версию:
+
+```bash
+./run_local_checks
+```
+
+## Как читать результат
+
+Скрипт печатает заголовок каждого шага (`==> Ruff lint` и так далее). При успехе в конце выводится `All checks passed.`
+
+Если какой-то шаг упал, исправьте замечания из его вывода и запустите скрипт снова. Форматирование можно исправить автоматически:
+
+```bash
+uv run ruff format src
+```

manuals/submit_homework.md

@@ -0,0 +1,30 @@
+# Сдача домашнего задания
+
+Чтобы работа была принята на проверку, выполните шаги ниже по порядку.
+
+## 1. Выполните задание
+
+Выполните все пункты задания и оформите решение в соответствующих файлах. Перед отправкой [запустите локальные проверки](local_checks.md), чтобы заранее найти ошибки в оформлении кода.
+
+## 2. Залейте решение в свой форк
+
+Решение должно лежать в вашем форке репозитория на GitHub. Если форка ещё нет, создайте его кнопкой **Fork** на странице исходного репозитория, затем закоммитьте изменения и отправьте их в форк:
+
+```bash
+git add .
+git commit -m "Solve task 1"
+git push
+```
+
+## 3. Откройте Pull Request
+
+Откройте Pull Request из своего форка в [исходный репозиторий](https://github.com/python-department/pl-001-python-basics-task).
+
+Оформите его так:
+
+- **Название** должно соответствовать шаблону: `номер задания. ФИО студента`. Пример: `1. Иванов Иван Иванович`.
+- **Лейбл**: поставьте лейбл вашей группы.
+
+## 4. Дождитесь результатов CI
+
+Pull Request будет проверен только в том случае, если он оформлен корректно (название и лейбл соответствуют требованиям), а все проверки CI пройдены успешно. Если какая-то проверка упала, исправьте замечания, запушьте изменения в тот же форк и дождитесь нового запуска CI.

run_local_checks

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# Run the same checks locally as in CI (.github/workflows/ci.yml).
+set -euo pipefail
+
+cd "$(dirname "$0")"
+
+if ! command -v uv >/dev/null 2>&1; then
+    echo "Error: uv is not installed. Install it: https://docs.astral.sh/uv/getting-started/installation/" >&2
+    exit 1
+fi
+
+echo "==> Install dependencies"
+uv sync --locked
+
+echo "==> Ruff lint"
+uv run ruff check src
+
+echo "==> Ruff format check"
+uv run ruff format --check src
+
+echo "==> MyPy"
+uv run mypy --strict src
+
+echo "All checks passed."

run_local_checks.bat

@@ -0,0 +1,23 @@
+@echo off
+rem Run the same checks locally as in CI (.github/workflows/ci.yml).
+cd /d "%~dp0"
+
+where uv >nul 2>nul
+if errorlevel 1 (
+    echo Error: uv is not installed. Install it: https://docs.astral.sh/uv/getting-started/installation/ 1>&2
+    exit /b 1
+)
+
+echo ==^> Install dependencies
+uv sync --locked || exit /b 1
+
+echo ==^> Ruff lint
+uv run ruff check src || exit /b 1
+
+echo ==^> Ruff format check
+uv run ruff format --check src || exit /b 1
+
+echo ==^> MyPy
+uv run mypy --strict src || exit /b 1
+
+echo All checks passed.