From af1585c634ee2b9033d666a1a8da49041b2afaad Mon Sep 17 00:00:00 2001 From: Lacky1234union Date: Mon, 12 Oct 2026 19:49:04 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20Gitea=20=E2=80=94=20=D0=BE=D1=81=D0=BD?= =?UTF-8?q?=D0=BE=D0=B2=D0=BD=D0=BE=D0=B9=20=D1=80=D0=B5=D0=BF=D0=BE=D0=B7?= =?UTF-8?q?=D0=B8=D1=82=D0=BE=D1=80=D0=B8=D0=B9=20=D0=B8=20=D1=82=D1=80?= =?UTF-8?q?=D0=B5=D0=BA=D0=B5=D1=80,=20SourceCraft=20=E2=80=94=20=D0=B7?= =?UTF-8?q?=D0=B5=D1=80=D0=BA=D0=B0=D0=BB=D0=BE=20(ADR-010)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Refs #22 Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 19 +++++++---- README.md | 2 ++ docs/ARCHITECTURE.md | 7 ++-- docs/DECISIONS.md | 14 +++++++- docs/SPEC.md | 2 +- docs/dev/GITEA_API.md | 67 +++++++++++++++++++++++++++++++++++++ docs/dev/SOURCECRAFT_API.md | 3 ++ docs/dev/WORKFLOW.md | 14 +++++++- 8 files changed, 117 insertions(+), 11 deletions(-) create mode 100644 docs/dev/GITEA_API.md diff --git a/CLAUDE.md b/CLAUDE.md index e244e89..e21a843 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,8 +6,14 @@ set -a; . ./.env 2>/dev/null; set +a ``` -`SOURCECRAFT_TOKEN` — токен SourceCraft API (секрет — **в чат не печатать**). Репозиторий: -[`rogachevegorushka/tgit`](https://sourcecraft.dev/rogachevegorushka/tgit). API → [`docs/dev/SOURCECRAFT_API.md`](docs/dev/SOURCECRAFT_API.md). +Переменные: `GITEA_URL`, `GITEA_TOKEN`, `GITEA_USER`, `GITEA_REPO`, `SOURCECRAFT_TOKEN` (токены — секрет, **в чат не печатать**). + +| Где | Что | Remote | +|---|---|---| +| [Gitea `HSE/tgit`](https://gitea.24studbank.ru/HSE/tgit) | **основной:** код, issues, PR, ревью | `origin` | +| [SourceCraft `rogachevegorushka/tgit`](https://sourcecraft.dev/rogachevegorushka/tgit) | зеркало (push-mirror из Gitea) + CI/CD | `sourcecraft` (только чтение) | + +⛔ В SourceCraft ничего не пушим и не мержим — зеркало перезапишет (ADR-010). --- @@ -31,7 +37,7 @@ Telegram-бот (учебный проект НИУ ВШЭ, курс Python): п ## Карта документации -> Задачи — в Issues на SourceCraft, не в файлах. +> Задачи — в [Gitea Issues](https://gitea.24studbank.ru/HSE/tgit/issues), не в файлах. | Файл | О чём | |------|-------| @@ -41,14 +47,15 @@ Telegram-бот (учебный проект НИУ ВШЭ, курс Python): п | [`docs/QUESTIONS_IDEAS.md`](docs/QUESTIONS_IDEAS.md) | Открытые вопросы, бэклог идей | | [`docs/dev/WORKFLOW.md`](docs/dev/WORKFLOW.md) | Регламент: ветки, коммиты, PR, жизненный цикл задачи | | [`docs/dev/ISSUE_TEMPLATE.md`](docs/dev/ISSUE_TEMPLATE.md) | Шаблон тела issue | -| [`docs/dev/SOURCECRAFT_API.md`](docs/dev/SOURCECRAFT_API.md) | SourceCraft API: curl-шпаргалка (issue, метки, PR) | +| [`docs/dev/GITEA_API.md`](docs/dev/GITEA_API.md) | Gitea API: issue, PR, зависимости, зеркало | +| [`docs/dev/SOURCECRAFT_API.md`](docs/dev/SOURCECRAFT_API.md) | SourceCraft API: CI-прогоны, логи, секреты | --- ## TL;DR — работа -1. **Задача = Issue.** Нет issue — нет кода. -2. **Ветка от `dev`:** `/-`. PR в `dev`; `dev → main` — только человек. +1. **Задача = Issue в Gitea.** Нет issue — нет кода. +2. **Ветка от `dev`:** `/-`. PR в `dev` (в Gitea); `dev → main` — только человек. 3. **Гейт зелёный:** lint + тесты перед PR. 4. **Завершил → push + PR** сразу. 5. **Лог выполнения** — в issue (`### YYYY-MM-DD`), архитектурные решения — в `DECISIONS.md`. diff --git a/README.md b/README.md index 715a0fc..6d97b33 100644 --- a/README.md +++ b/README.md @@ -10,3 +10,5 @@ - ТЗ: [`docs/SPEC.md`](docs/SPEC.md) - Архитектура: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) - Как работаем: [`docs/dev/WORKFLOW.md`](docs/dev/WORKFLOW.md) + +Основной репозиторий и задачи — [Gitea `HSE/tgit`](https://gitea.24studbank.ru/HSE/tgit); [SourceCraft](https://sourcecraft.dev/rogachevegorushka/tgit) — зеркало с CI/CD. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 88666c2..78c71ce 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -33,7 +33,7 @@ | Репозиторий | Что внутри | CI/CD | |---|---|---| -| `tgit` | код бота | PR/push `dev`: lint + types + tests; push `main`: + деплой бота на хост | +| `tgit` (Gitea → зеркало в SourceCraft) | код бота | push в любую ветку: lint + types + tests; push `main`: + деплой бота на хост | | `tgit-uploads` | `projects//…` от пользователей | push `main`: проверки проекта; успех → `ssh tgit-runner deploy ` | ## 2. Компоненты @@ -142,9 +142,12 @@ docker run -d --name tgit-app- --label tgit.project= --label t ## 5. CI/CD ### 5.1 Репозиторий бота (`tgit/.sourcecraft/ci.yaml`) + +Код живёт в Gitea, SourceCraft получает его push-зеркалом и запускает CI/CD (ADR-010). + | Триггер | Workflow | Шаги | |---|---|---| -| PR в `dev`/`main`, push в `dev` | `check` | `uv sync --frozen` → `ruff check` + `ruff format --check` → `mypy app` → `pytest --cov=app --cov-fail-under=70` | +| push в любую ветку (через зеркало Gitea; PR живут в Gitea — ADR-010) | `check` | `uv sync --frozen` → `ruff check` + `ruff format --check` → `mypy app` → `pytest --cov=app --cov-fail-under=70` | | push в `main` | `check` + `deploy` | → `infra/deploy/deploy.sh` по SSH (секреты `DEPLOY_SSH_KEY`, `DEPLOY_HOST`) → smoke: healthcheck контейнера | ### 5.2 Репозиторий загрузок (`tgit-uploads/.sourcecraft/ci.yaml`) diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md index 4deadaf..e8d4016 100644 --- a/docs/DECISIONS.md +++ b/docs/DECISIONS.md @@ -15,7 +15,7 @@ --- ## ADR-001: Хостинг кода и задач — SourceCraft -**Дата:** 2026-10-12 · **Статус:** принято +**Дата:** 2026-10-12 · **Статус:** заменено ADR-010 **Контекст:** нужен репозиторий проекта, трекер задач и CI. **Решение:** код бота, issues и CI — на SourceCraft. Загрузки пользователей — в отдельный репозиторий там же. @@ -84,3 +84,15 @@ **Решение:** Python 3.12, uv, aiogram 3, httpx, pydantic-settings, SQLAlchemy 2 async + Alembic, PostgreSQL 16, `regex`, pytest (+ pytest-asyncio, respx), ruff, mypy. Контейнеризация — Docker Compose. **Альтернативы:** python-telegram-bot — синхронное наследие в API; SQLite в проде — проще, но Postgres ближе к реальным сервисам и уже привычен по Vobot/meditron. **Последствия:** тесты на SQLite через тот же SQLAlchemy. + +## ADR-010: Gitea — основной репозиторий и трекер, SourceCraft — зеркало + CI/CD +**Дата:** 2026-10-12 · **Статус:** принято (заменяет ADR-001) + +**Контекст:** веб-интерфейс SourceCraft работает нестабильно и часть функций отображает плохо; API периодически рвёт соединения. При этом CI/CD на SourceCraft — часть постановки преподавателя. +**Решение:** код, issues, PR и ревью — в Gitea [`HSE/tgit`](https://gitea.24studbank.ru/HSE/tgit) (как Vobot/meditron). Встроенный push-mirror Gitea синхронизирует репозиторий в SourceCraft на каждый push (+ раз в 8 ч); CI/CD бота и репозиторий загрузок `tgit-uploads` остаются в SourceCraft. +**Альтернативы:** только SourceCraft — неудобно работать; только Gitea (Gitea Actions) — уходим от постановки; зеркало по SSH — на этом Gitea SSH-зеркала отключены, поэтому HTTPS + токен SourceCraft. +**Последствия:** +- В SourceCraft ничего не пушим и не мержим — зеркало перезаписывает его целиком. +- Триггер `pull_request` в SourceCraft не срабатывает (PR живут в Gitea) → CI бота запускается на `push` во все ветки. +- Токен SourceCraft хранится в настройках зеркала Gitea → нужен отдельный токен с доступом только к `tgit`. +- Issues #1–#21 перенесены из SourceCraft с теми же номерами; в SourceCraft закрыты со ссылкой. diff --git a/docs/SPEC.md b/docs/SPEC.md index f57d11f..845fc57 100644 --- a/docs/SPEC.md +++ b/docs/SPEC.md @@ -26,7 +26,7 @@ | Термин | Значение | |---|---| -| **Репозиторий бота** | [`rogachevegorushka/tgit`](https://sourcecraft.dev/rogachevegorushka/tgit) — код самого бота | +| **Репозиторий бота** | Gitea [`HSE/tgit`](https://gitea.24studbank.ru/HSE/tgit) (основной) → зеркало [`rogachevegorushka/tgit`](https://sourcecraft.dev/rogachevegorushka/tgit) в SourceCraft, где работает CI/CD | | **Репозиторий загрузок** | `rogachevegorushka/tgit-uploads` — сюда бот коммитит файлы пользователей | | **Проект** | Папка `projects//` в репозитории загрузок; единица запуска и мониторинга | | **Загрузка** | Один отправленный файл → один коммит | diff --git a/docs/dev/GITEA_API.md b/docs/dev/GITEA_API.md new file mode 100644 index 0000000..927bc69 --- /dev/null +++ b/docs/dev/GITEA_API.md @@ -0,0 +1,67 @@ +# Gitea API — шпаргалка + +Gitea — основной репозиторий и трекер: [`HSE/tgit`](https://gitea.24studbank.ru/HSE/tgit). SourceCraft — зеркало (ADR-010). + +> **Кириллица в JSON:** не собирать тело в `curl -d '{...}'` руками — ломается кодировка и экранирование. +> Тело собираем в Python (`json.dumps(..., ensure_ascii=False)`) в файл и отправляем `--data @file.json`. + +```bash +set -a; . ./.env; set +a # GITEA_URL, GITEA_TOKEN, GITEA_USER, GITEA_REPO +G="$GITEA_URL/api/v1/repos/$GITEA_REPO" +A="Authorization: token $GITEA_TOKEN" +J="Content-Type: application/json; charset=utf-8" +alias curl='curl --retry 4 --retry-all-errors --retry-delay 2' +``` + +> Сервер иногда рвёт SSH (`Connection closed … port 2222`) и медленно отвечает на запись — повторять, перед повторным +> POST проверять, не создалась ли сущность. + +## Issues + +```bash +# мои открытые +curl -s -H "$A" "$G/issues?state=open&type=issues&assigned_by=$GITEA_USER" + +# создать: {"title","body","labels":[id…],"milestone":id,"assignees":["$GITEA_USER"]} +curl -s -X POST -H "$A" -H "$J" "$G/issues" --data @issue.json + +# обновить тело / закрыть +curl -s -X PATCH -H "$A" -H "$J" "$G/issues/NN" --data @body.json # {"body": "..."} +curl -s -X PATCH -H "$A" -H "$J" "$G/issues/NN" -d '{"state":"closed"}' + +# комментарий +curl -s -X POST -H "$A" -H "$J" "$G/issues/NN/comments" --data @comment.json # {"body": "..."} + +# метки и вехи — по id +curl -s -H "$A" "$G/labels" +curl -s -H "$A" "$G/milestones?state=all" +``` + +## Зависимости (только через API, не текстом в теле) + +```bash +# #NN зависит от #MM (MM блокирует NN) +curl -s -X POST -H "$A" -H "$J" "$G/issues/NN/dependencies" -d "{\"owner\":\"${GITEA_REPO%%/*}\",\"repo\":\"${GITEA_REPO##*/}\",\"index\":MM}" +curl -s -H "$A" "$G/issues/NN/dependencies" +``` + +## Pull requests + +```bash +# PR в dev (не в main!); тело — с "Closes #NN" +curl -s -X POST -H "$A" -H "$J" "$G/pulls" --data @pr.json # {"head":"feat/NN-slug","base":"dev","title":"…","body":"…"} + +# ветка ещё есть? пусто → PR смержен, не пушить +git ls-remote --heads origin <ветка> +``` + +## Зеркало в SourceCraft + +```bash +curl -s -H "$A" "$G/push_mirrors" # статус: last_update, last_error +curl -s -X POST -H "$A" "$G/push_mirrors-sync" # синхронизировать сейчас +``` + +Зеркало — HTTPS (`git.sourcecraft.dev`) с токеном SourceCraft: SSH-зеркала на этом Gitea отключены. +Синхронизация — на каждый push + раз в 8 часов. Зеркало перезаписывает SourceCraft целиком (`--mirror`): +**в SourceCraft ничего не пушим и не мержим** — изменения пропадут. diff --git a/docs/dev/SOURCECRAFT_API.md b/docs/dev/SOURCECRAFT_API.md index 249811a..d84cece 100644 --- a/docs/dev/SOURCECRAFT_API.md +++ b/docs/dev/SOURCECRAFT_API.md @@ -1,5 +1,8 @@ # SourceCraft API — шпаргалка +> Issues и PR ведём в Gitea ([`GITEA_API.md`](GITEA_API.md), ADR-010). Здесь нужны в основном CI-прогоны, логи и секреты; +> разделы про issues/метки/PR — справочно (бот и скрипты могут работать с `tgit-uploads`). + Справочник: [методы](https://sourcecraft.dev/portal/docs/en/api-ref/index.md) · [интерактивный](https://api.sourcecraft.tech/docs/index.html) · [swagger.json](https://api.sourcecraft.tech/sourcecraft.swagger.json) diff --git a/docs/dev/WORKFLOW.md b/docs/dev/WORKFLOW.md index fa7f5e7..8812202 100644 --- a/docs/dev/WORKFLOW.md +++ b/docs/dev/WORKFLOW.md @@ -2,7 +2,8 @@ ## Откуда задачи -- Только из Issues на SourceCraft. Нет issue → завести → потом код. API: [`SOURCECRAFT_API.md`](SOURCECRAFT_API.md). +- Только из [Gitea Issues](https://gitea.24studbank.ru/HSE/tgit/issues). Нет issue → завести → потом код. API: [`GITEA_API.md`](GITEA_API.md). +- Зависимости между issue — через API Gitea, не текстом в теле. - Атрибуты issue: исполнитель, метка зоны (`bot` / `ci` / `infra` / `llm` / `docs`), тип (`feature` / `fix` / `refactor` / `docs`), размер (`size/0.5` ≈ 2ч · `size/1` ≈ 4ч · `size/2` ≈ 1д). - Тело — по [`ISSUE_TEMPLATE.md`](ISSUE_TEMPLATE.md). @@ -20,6 +21,17 @@ 8. Мерж → ветку удалить ``` +## Репозитории + +``` +Gitea HSE/tgit (origin) ──push-mirror (на каждый push)──► SourceCraft rogachevegorushka/tgit + код · issues · PR · ревью CI/CD (.sourcecraft/ci.yaml) +``` + +- Работаем только с `origin` (Gitea). Remote `sourcecraft` — для чтения/сверки. +- ⛔ В SourceCraft не пушим, не мержим, PR не открываем: зеркало перезаписывает его целиком. +- CI SourceCraft запускается пушем зеркала; результат смотрим там же (ссылка — в PR вручную или через бота, когда будет). + ## Ветки ```