feat: implement versioning and release management in the project

- Added automatic versioning based on git tags using semantic-release in Gitea Actions.
- Introduced new API endpoints `GET /version` and `GET /v1/version` to expose build metadata.
- Updated Docker build process to include version and build time information in Go binaries.
- Enhanced documentation with details on release processes and versioning guidelines.
- Integrated version display in the web application for better user visibility.

docs/README.md

@@ -20,6 +20,7 @@
 | [api.md](api.md) | REST: префикс `/v1`, публичные маршруты, ссылки на OpenAPI |
 | [router-lists-ui-integration.md](router-lists-ui-integration.md) | Интеграция `router-lists-ui` с EvoBGP API (`DOMAINS/IP_RANGES/AS_PREFIXES/communities`) |
 | [access.md](access.md) | Выдача доступа: API-ключи, роли, нода, CORS |
+| [releasing.md](releasing.md) | Автоматические релизы, Conventional Commits, CI |
 | [openapi.yaml](openapi.yaml) | Источник правды по контракту API |
 | [OPENAPI-GITEA.md](OPENAPI-GITEA.md) | Как открыть HTML-документацию API (в т.ч. из Gitea) |
 | [evobgp-api-sketches.md](evobgp-api-sketches.md) | Ранний черновик идей API (контекст, не замена OpenAPI) |
@@ -40,3 +41,4 @@
 ## Репозиторий и CI
 
 - [../.gitea/README.md](../.gitea/README.md) — Gitea Actions, runner, сборка образов и push в Container Registry.
+- [releasing.md](releasing.md) — semantic-release, commit conventions, теги образов.

docs/openapi.yaml

@@ -1,10 +1,12 @@
 openapi: 3.1.0
 info:
   title: EvoBGP Control Plane API
-  version: 0.1.0
+  version: 1.0.0
   description: |
     REST API управления префиксами, модулями ingest, ревизиями конфигурации BIRD и задачами (async jobs).
 
+    **Актуальная semver-сборка:** `GET /version` или `GET /v1/version` (поле `version`; совпадает с git-тегом `vX.Y.Z`).
+
     **Соглашения:** префикс `/v1`; идентификаторы - UUID v7 или ULID (строки); время - ISO 8601 UTC.
     Ошибки - `application/problem+json` ([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)).
     Пагинация списков - `cursor` + `limit`; ответ содержит `items`, `next_cursor`, `has_more`.
@@ -758,8 +760,14 @@ components:
     VersionInfo:
       type: object
       properties:
+        version:
+          type: string
+          description: Semver сборки (git tag без префикса v).
+          example: "1.2.3"
         api_version:
           type: string
+          deprecated: true
+          description: Alias поля `version` (сохранён для обратной совместимости).
         git_sha:
           type: string
         build_time:
@@ -967,11 +975,31 @@ paths:
         default:
           $ref: "#/components/responses/DefaultProblem"
 
+  /version:
+    get:
+      tags: [System]
+      summary: Версия сборки (корневой путь)
+      description: |
+        Аналог `GET /v1/version`. Публичный маршрут без аутентификации.
+        Semver в поле `version` задаётся при сборке Docker-образов из git-тега.
+      operationId: getVersionRoot
+      responses:
+        "200":
+          description: Метаданные сборки.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/VersionInfo"
+        default:
+          $ref: "#/components/responses/DefaultProblem"
+
   /v1/version:
     get:
       tags: [System]
       summary: Версия сборки
-      description: Версия API и control-plane (`git_sha`, `build_time` и др.).
+      description: |
+        Semver control-plane и метаданные сборки (`git_sha`, `build_time`).
+        Дублирует `GET /version`.
       operationId: getVersion
       responses:
         "200":

docs/releasing.md

@@ -0,0 +1,83 @@
+# Релизы и версионирование EvoBGP
+
+EvoBGP использует [Conventional Commits](https://www.conventionalcommits.org/) и [semantic-release](https://semantic-release.gitbook.io/) для полностью автоматических релизов на Gitea (`git.shts.su`). Ручное повышение версии в коде не требуется.
+
+## Как определяется версия
+
+| Тип коммита | Bump |
+|-------------|------|
+| `feat` | minor (1.0.0 → 1.1.0) |
+| `fix`, `perf` | patch (1.0.0 → 1.0.1) |
+| `feat!`, `fix!` или `BREAKING CHANGE:` в теле | major (1.0.0 → 2.0.0) |
+| `docs`, `chore`, `ci`, `test`, `refactor` | без релиза |
+
+Первый релиз при отсутствии git-тегов — **1.0.0**, если есть releasable-коммиты.
+
+Подробные правила сообщений коммитов: [.cursor/rules/conventional-commits.mdc](../.cursor/rules/conventional-commits.mdc).
+
+## CI-пайплайн
+
+```text
+push/merge в main
+  → CI (openapi, web, go, bird2, commitlint на PR)
+  → Release (semantic-release после успешного CI)
+       → git tag vX.Y.Z
+       → CHANGELOG.md + commit [skip ci]
+       → Gitea Release с notes
+  → Publish (push тега v*)
+       → docker buildx bake с VERSION из тега
+       → образы: latest, vX.Y.Z, sha-*, короткий SHA
+```
+
+Workflow-файлы:
+
+- [.gitea/workflows/ci.yaml](../.gitea/workflows/ci.yaml) — quality gates
+- [.gitea/workflows/release.yaml](../.gitea/workflows/release.yaml) — semantic-release
+- [.gitea/workflows/publish.yaml](../.gitea/workflows/publish.yaml) — публикация образов
+
+Конфиг semantic-release: [.releaserc.json](../.releaserc.json).
+
+## Секреты Gitea
+
+Один PAT в репозитории — **`ACTIONS_PAT`** (Settings → Actions → Secrets). Используется для semantic-release, push тегов/CHANGELOG и docker login в registry.
+
+| Право PAT | Зачем |
+|-----------|--------|
+| push / write repository | commit `CHANGELOG.md`, push тегов |
+| releases | Gitea Release через semantic-release |
+| packages (Container Registry) | workflow **Publish** |
+
+Если `ACTIONS_PAT` не задан, workflow пробует **`gitea.token`** job-токен (нужны права на releases и packages в настройках Gitea).
+
+## Источник правды для версии в runtime
+
+Semver из git-тега пробрасывается в Go-бинарники через `-ldflags` при сборке Docker (`deploy/docker/gobinary/Dockerfile`). Пакет [`internal/version`](../internal/version/version.go):
+
+- локально (`go run`) — `version: "dev"`
+- в образе после релиза — совпадает с тегом (например `1.2.3`)
+
+API:
+
+- `GET /version`
+- `GET /v1/version`
+
+Ответ включает `version`, `git_sha`, `build_time`; поле `api_version` — deprecated alias.
+
+Web UI показывает версию из API (footer sidebar, страница «Мониторинг»).
+
+## CHANGELOG
+
+Файл [`CHANGELOG.md`](../CHANGELOG.md) создаётся и обновляется semantic-release. Копия прикрепляется к Gitea Release.
+
+## Проверка после релиза
+
+1. В Gitea: тег `vX.Y.Z` и Release с notes.
+2. Container Registry: образы с тегом `vX.Y.Z`.
+3. `curl http://localhost:8080/version` → `"version":"X.Y.Z"`.
+4. Footer Web UI → `vX.Y.Z`.
+
+## Первый релиз (bootstrap)
+
+Merge PR в `main` с conventional commit типа `feat(release): ...` (не `chore` — иначе релиз не создастся). Ожидаемый результат: **v1.0.0**.
+
+После merge убедитесь, что workflow **Release** завершился успешно и workflow **Publish** собрал образы по тегу.