From fa9dd662b8930a91fb087fbe9110ed2066113655 Mon Sep 17 00:00:00 2001
From: Andrewkydev <grusha.belaev@gmail.com>
Date: Sun, 31 May 2026 13:44:39 +0300
Subject: [PATCH] docs: add contributor guide and compatibility matrix

---
 CONTRIBUTING.md | 44 ++++++++++++++++++++++++++++++++++++++++++++
 README.md       | 18 ++++++++++++++++++
 README.ru.md    | 18 ++++++++++++++++++
 3 files changed, 80 insertions(+)
 create mode 100644 CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..5e3fd0c
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,44 @@
+# Contributing to AstraDeploy
+
+Спасибо за интерес к проекту! Любой вклад welcome: фиксы багов, улучшения UX, новые ядра, новые локали.
+
+## Как разрабатывать
+
+1. Склонируйте/проверьте локальный репозиторий.
+2. Работайте в отдельной ветке (рекомендуется).
+3. Изменения делайте минимальными и атомарными по смыслу.
+4. Смотрите локаль: тексты и подсказки лучше держать в `locales/*.sh`, а не разбрасывать по скриптам.
+
+## Полезные принципы
+
+- `install.sh` хранит общий lifecycle; ядра — в `cores/*.sh`.
+- Не меняйте поведение без флага по умолчанию, если это может сломать автоматический режим.
+- Для новых параметров:
+  - добавьте парсинг в `install.sh`;
+  - добавьте локализацию в `locales/en.sh` и `locales/ru.sh`;
+  - проверьте сценарии `--yes`, `--easy`, `--dry-run`, `--force-clean`, `--accept-license`.
+- При добавлении новых ядер:
+  - создайте новый файл в `cores/`;
+  - добавьте запись в `manifests/cores.json`;
+  - обновите `install.sh --help` список ядер.
+
+## Стиль и формат
+
+- Bash: избегайте сложных однострочников, лучше явные переменные и функции.
+- Локали и тексты: используйте существующие ключи/шаблоны в `locales`.
+- Логи: новые важные шаги добавляйте через `info/warn/error` из `lib/logger.sh`.
+
+## Отладка и проверки
+
+- Для быстрого прогона используйте `--dry-run`.
+- При проблемах с внешним окружением:
+  - `--debug` покажет расширенные шаги;
+  - просматривайте лог в `/var/log/astra-deploy/`.
+- Проверки не должны ломать установку на старте — лучше мягко предупреждать и продолжать fallback-логикой.
+
+## Pull Request
+
+1. Коротко опишите, что меняется и почему.
+2. Приложите сценарий проверки (команды/флаги), который вы прогоняли.
+3. Укажите совместимые ОС/ядра и известные ограничения.
+
diff --git a/README.md b/README.md
index cf6796f..8addedd 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,20 @@ Current version: `v0.1.0`.
 - `sudo` / root privileges
 - Internet access for downloading binaries/artifacts
 
+## Compatibility matrix
+
+| Environment | Status | Notes |
+|---|---|---|
+| Ubuntu / Debian | ✅ Supported | Primary target for initial MVP (`apt`) |
+| Alma / Rocky / RHEL-family | ⚠️ Partial | Planned support paths exist, but this release focuses on core workflow verification |
+| Arch Linux | ⚠️ Partial | Generic support path in architecture, not fully validated in this release |
+| Fedora | ⚠️ Partial | Generic support path in architecture, not fully validated in this release |
+| `yum` / `dnf` | ⚠️ Partial | Service/dependency handling is planned for full parity |
+| `pacman` | ⚠️ Partial | Detection and abstraction are present, full validation pending |
+| `tmux` | ✅ Supported | Required for `tmux-systemd` mode |
+| `screen` | ✅ Supported | Optional service transport |
+| `systemd` | ✅ Supported | Required for autostart service modes |
+
 ## Supported cores
 
 | Core | Default directory | Default port | Runtime | Protocol | Notes |
@@ -204,3 +218,7 @@ sudo bash install.sh --version
 ## Changelog
 
 See [`CHANGELOG.md`](CHANGELOG.md).
+
+## Contributing
+
+Please read [`CONTRIBUTING.md`](CONTRIBUTING.md).
diff --git a/README.ru.md b/README.ru.md
index 7a77b32..7350d85 100644
--- a/README.ru.md
+++ b/README.ru.md
@@ -22,6 +22,20 @@
 - права `root` (или `sudo`)
 - доступ в интернет для загрузки артефактов
 
+## Матрица совместимости
+
+| Окружение | Статус | Комментарий |
+|---|---|---|
+| Ubuntu / Debian | ✅ Поддерживается | Основная целевая платформа для текущего MVP (`apt`) |
+| Alma / Rocky / RHEL-семейство | ⚠️ Частично | Роуты поддержки запланированы, финальная валидация в работе |
+| Arch Linux | ⚠️ Частично | Архитектурно предусмотрена поддержка, но пока не полностью провалидирована |
+| Fedora | ⚠️ Частично | Архитектурно предусмотрена поддержка, но пока не полностью провалидирована |
+| `yum` / `dnf` | ⚠️ Частично | Нужна доработка до полной валидации сервисов/зависимостей |
+| `pacman` | ⚠️ Частично | Есть детект и абстракция, полная валидация в следующих релизах |
+| `tmux` | ✅ Поддерживается | Требуется для режима `tmux-systemd` |
+| `screen` | ✅ Поддерживается | Опциональный тип запуска сервиса |
+| `systemd` | ✅ Поддерживается | Нужен для автозапуска в service-режимах |
+
 ## Поддерживаемые ядра
 
 | Ядро | Директория по умолчанию | Порт | Runtime | Протокол | Примечание |
@@ -201,6 +215,10 @@ sudo bash install.sh \
 sudo bash install.sh --version
 ```
 
+## Contributing
+
+См. [`CONTRIBUTING.md`](CONTRIBUTING.md) для правил участия.
+
 ## Changelog
 
 См. [`CHANGELOG.md`](CHANGELOG.md).