diff --git a/README.md b/README.md index 99bda938..48f42e21 100644 --- a/README.md +++ b/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-битных числовых идентификаторов, в которые упакованы метка времени, номер узла и счётчик последовательности. Такие идентификаторы уникальны и примерно упорядочены по времени, а из самого идентификатора можно узнать, когда и на каком узле он был создан. diff --git a/manuals/local_checks.md b/manuals/local_checks.md new file mode 100644 index 00000000..4554d610 --- /dev/null +++ b/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 +``` diff --git a/manuals/submit_homework.md b/manuals/submit_homework.md new file mode 100644 index 00000000..02133283 --- /dev/null +++ b/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. diff --git a/run_local_checks b/run_local_checks new file mode 100755 index 00000000..7345200f --- /dev/null +++ b/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." diff --git a/run_local_checks.bat b/run_local_checks.bat new file mode 100644 index 00000000..e1b1ce9e --- /dev/null +++ b/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.