docs: обновлена документация и help для линтинга ролей

- Обновлена основная справка make help с примерами использования - Добавлена подробная справка по линтингу в make role - Создана документация docs/linting-guide.md с полным руководством - Обновлен README.md с примерами команд линтинга - Добавлена ссылка на новую документацию в секции разработки Новая документация включает: - Команды линтинга (все роли и конкретные) - Профили линтинга (production, basic, min) - Типы ошибок и способы исправления - Интеграция с CI/CD - Лучшие практики и устранение неполадок
2025-10-25 20:44:51 +03:00
parent b315bc6b14
commit 34e0cbd570
3 changed files with 253 additions and 5 deletions
--- a/27
+++ b/27
@@ -147,7 +147,11 @@ role:
 			echo "     💡 Использует: ansible-lint"; \
 			echo "     💡 Без параметра: проверяет все роли"; \
 			echo "     💡 С параметром: проверяет конкретную роль"; \
-			echo "     💡 Примеры: make role lint, make role lint devops"; \
+			echo "     💡 Валидация: показывает доступные роли при ошибке"; \
+			echo "     💡 Примеры:"; \
+			echo "       make role lint                    # проверить все роли"; \
+			echo "       make role lint devops             # проверить только devops"; \
+			echo "       make role lint ping               # проверить только ping"; \
 			echo ""; \
 			echo "  📋 make role list           - показать все роли"; \
 			echo "     💡 Показывает: список всех ролей в roles/"; \
@@ -160,7 +164,14 @@ role:
 			echo "  🗑️  make role delete         - удалить роль"; \
 			echo "     💡 Интерактивно: запрашивает имя роли"; \
 			echo "     💡 Удаляет: папку роли и файлы"; \
-			echo "     💡 Обновляет: roles/deploy.yml";; \
+			echo "     💡 Обновляет: roles/deploy.yml"; \
+			echo ""; \
+			echo "  🔧 ДОПОЛНИТЕЛЬНАЯ ИНФОРМАЦИЯ О ЛИНТИНГЕ:"; \
+			echo "     💡 Линтинг проверяет: синтаксис, стиль, лучшие практики"; \
+			echo "     💡 Профили: production, basic, min"; \
+			echo "     💡 Конфигурация: .ansible-lint"; \
+			echo "     💡 Ошибки: показываются с номерами строк"; \
+			echo "     💡 Валидация: автоматическая проверка существования роли";; \
 	esac

 # =============================================================================
@@ -948,15 +959,23 @@ help:
 	@echo "  dockerfiles/      - Docker образы для тестирования"
 	@echo ""
 	@echo "🚀 ОСНОВНЫЕ КОМАНДЫ:"
-	@echo "  make role lint [role]     - проверить синтаксис ролей (все или конкретную)"	
+	@echo "  make role lint [role]     - проверить синтаксис ролей (все или конкретную)"
+	@echo "    💡 Примеры: make role lint, make role lint devops"
 	@echo "  make role test [preset]  - протестировать роли с preset'ом"
 	@echo "  make role deploy         - развернуть роли на реальные серверы"
 	@echo "  make role list           - показать все роли"
 	@echo "  make role create         - создать новую роль (интерактивно)"
 	@echo "  make role delete         - удалить роль (интерактивно)"
 	@echo ""
-	@echo "📖 ДОКУМЕНТАЦИЯ ПО DEPLOY.YML:"
+	@echo "📖 ДОКУМЕНТАЦИЯ:"
 	@echo "  docs/deploy-yml-customization.md - полное руководство по кастомизации"
+	@echo "  docs/linting-guide.md - руководство по линтингу ролей"
+	@echo ""
+	@echo "🔍 ЛИНТИНГ РОЛЕЙ:"
+	@echo "  make role lint [role]     - проверить синтаксис (все или конкретную роль)"
+	@echo "  💡 Профили: production, basic, min"
+	@echo "  💡 Конфигурация: .ansible-lint"
+	@echo "  💡 Валидация: автоматическая проверка существования роли"
 	@echo ""
 	@echo "📋 PRESET'Ы (тестовые окружения):"
 	@echo "  make presets list        - показать все доступные preset'ы"
--- a/README.md
+++ b/README.md
@@ -15,6 +15,7 @@ AnsibleLab - это универсальная система для тести

 ### 🛠️ Разработка
 - **[docs/creating-roles.md](docs/creating-roles.md)** - Создание и разработка ролей
+- **[docs/linting-guide.md](docs/linting-guide.md)** - Руководство по линтингу ролей
 - **[docs/site-yml-guide.md](docs/site-yml-guide.md)** - Руководство по файлу site.yml
 - **[docs/molecule-guide.md](docs/molecule-guide.md)** - Подробное руководство по Molecule
 - **[docs/all-images-preset.md](docs/all-images-preset.md)** - Пресет all-images для тестирования всех образов
@@ -489,7 +490,9 @@ make role create
 make role delete

 # Проверка синтаксиса ролей
-make role lint
+make role lint                    # проверить все роли
+make role lint devops             # проверить конкретную роль
+make role lint ping               # проверить другую роль
 ```

 ### Docker команды
--- a/docs/linting-guide.md
+++ b/docs/linting-guide.md
@@ -0,0 +1,226 @@
+# 🔍 Руководство по линтингу ролей
+
+## Автор
+Сергей Антропов  
+Сайт: https://devops.org.ru
+
+## Обзор
+
+Линтинг ролей - это автоматическая проверка синтаксиса, стиля и соответствия лучшим практикам Ansible. В AnsibleTemplate используется `ansible-lint` для обеспечения качества кода.
+
+## Команды линтинга
+
+### Проверка всех ролей
+```bash
+make role lint
+```
+- Проверяет все роли в директории `roles/`
+- Использует конфигурацию из `.ansible-lint`
+- Показывает все найденные ошибки и предупреждения
+
+### Проверка конкретной роли
+```bash
+make role lint devops
+make role lint ping
+```
+- Проверяет только указанную роль
+- Автоматически валидирует существование роли
+- Показывает доступные роли при ошибке
+
+## Профили линтинга
+
+Ansible-lint использует несколько профилей для разных уровней строгости:
+
+### Production (по умолчанию)
+- Самый строгий профиль
+- Проверяет все правила
+- Рекомендуется для продакшн кода
+
+### Basic
+- Базовые правила
+- Подходит для разработки
+- Менее строгий чем production
+
+### Min
+- Минимальные правила
+- Только критичные ошибки
+- Для быстрой проверки
+
+## Конфигурация
+
+Линтинг настраивается через файл `.ansible-lint`:
+
+```yaml
+---
+# Профиль по умолчанию
+profile: production
+
+# Исключения
+skip_list:
+  - yaml[line-length]  # Исключить проверку длины строк
+
+# Дополнительные правила
+enable_list:
+  - name[casing]  # Включить проверку именования
+
+# Игнорирование файлов
+exclude_paths:
+  - .cache/
+  - .github/
+  - tests/
+```
+
+## Типы ошибок
+
+### Синтаксические ошибки
+- Неправильный YAML синтаксис
+- Ошибки в Jinja2 шаблонах
+- Неправильная структура playbook
+
+### Стилистические ошибки
+- Trailing spaces (лишние пробелы)
+- Неправильные комментарии
+- Неправильное форматирование
+
+### Лучшие практики
+- Использование устаревших модулей
+- Неправильное использование become
+- Отсутствие changed_when для command
+
+## Примеры исправлений
+
+### Trailing spaces
+```yaml
+# ❌ Неправильно
+  groups: ["sudo", "docker"]  
+  # Лишние пробелы в конце строки
+
+# ✅ Правильно
+  groups: ["sudo", "docker"]
+```
+
+### Комментарии
+```yaml
+# ❌ Неправильно
+#Комментарий без пробела
+
+# ✅ Правильно
+# Комментарий с пробелом
+```
+
+### Changed when
+```yaml
+# ❌ Неправильно
+- name: "Проверка статуса"
+  command: "systemctl status nginx"
+
+# ✅ Правильно
+- name: "Проверка статуса"
+  command: "systemctl status nginx"
+  changed_when: false
+```
+
+## Автоматическое исправление
+
+Некоторые ошибки можно исправить автоматически:
+
+```bash
+# Исправить trailing spaces
+sed -i 's/[[:space:]]*$//' roles/*/tasks/*.yml
+
+# Исправить комментарии
+sed -i 's/^#\([^ ]\)/# \1/' roles/*/tasks/*.yml
+```
+
+## Интеграция с CI/CD
+
+Линтинг автоматически запускается в CI/CD пайплайне:
+
+```yaml
+# .github/workflows/lint.yml
+name: Lint
+on: [push, pull_request]
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Run lint
+        run: make role lint
+```
+
+## Лучшие практики
+
+### 1. Регулярная проверка
+```bash
+# Проверяйте код перед коммитом
+make role lint
+
+# Проверяйте конкретную роль при разработке
+make role lint devops
+```
+
+### 2. Исправляйте ошибки сразу
+- Не накапливайте ошибки
+- Исправляйте по мере обнаружения
+- Используйте автоматические исправления
+
+### 3. Настройте IDE
+- Включите поддержку YAML
+- Настройте автоформатирование
+- Используйте расширения для Ansible
+
+### 4. Используйте pre-commit hooks
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: https://github.com/ansible/ansible-lint
+    rev: v6.0.0
+    hooks:
+      - id: ansible-lint
+```
+
+## Устранение неполадок
+
+### Ошибка "Role not found"
+```bash
+❌ Роль 'nonexistent' не найдена в roles/
+📋 Доступные роли:
+  - devops
+  - ping
+```
+**Решение**: Проверьте правильность имени роли
+
+### Ошибка "Docker image not found"
+```bash
+Unable to find image 'ansible-controller:latest' locally
+```
+**Решение**: Соберите Docker образы:
+```bash
+make docker build
+```
+
+### Ошибка "Permission denied"
+```bash
+Permission denied: /workspace/roles/
+```
+**Решение**: Проверьте права доступа к файлам
+
+## Дополнительные ресурсы
+
+- [Ansible Lint Documentation](https://ansible.readthedocs.io/projects/lint/)
+- [Ansible Best Practices](https://docs.ansible.com/ansible/latest/user_guide/playbooks_best_practices.html)
+- [YAML Style Guide](https://yaml.org/spec/1.2/spec.html)
+
+## Поддержка
+
+Если у вас возникли вопросы или проблемы с линтингом:
+
+1. Проверьте документацию выше
+2. Запустите `make role lint` для диагностики
+3. Обратитесь к команде разработки
+
+---
+
+**Последнее обновление**: $(date)  
+**Версия**: 1.0.0