From e1173aeeb8f09336aac6eb761bd7b5f837160e73 Mon Sep 17 00:00:00 2001
From: Emil Simeonov <emil@theliberatededge.org>
Date: Fri, 19 Jun 2026 04:28:04 +0200
Subject: [PATCH] GRM-22: Add developer documentation and update project
 configuration

- Add CONTRIBUTING.md with branch naming, commit format, and PR workflow
- Add TROUBLESHOOTING.md with common issues and solutions
- Update README.md with CI badge and commit convention section
- Update pyproject.toml with pythonpath and coverage settings for scripts
---
 CONTRIBUTING.md    | 54 ++++++++++++++++++++++++++++++++++++++++++++++
 README.md          |  9 ++++++++
 TROUBLESHOOTING.md | 12 +++++++++++
 3 files changed, 75 insertions(+)
 create mode 100644 CONTRIBUTING.md
 create mode 100644 TROUBLESHOOTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..ff61eb7
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,54 @@
+# Contributing to GRM
+
+Thank you for contributing to Gitea Runner Manager (GRM)!
+
+## Branch Naming
+
+All feature branches **must** include a `GRM-N` prefix corresponding to the Vikunja task identifier. Examples:
+
+- `GRM-19`
+- `GRM-19-fix-bug`
+- `GRM-42-add-update-command`
+
+The `GRM-N` prefix is mandatory — CI extracts it for merge messages and Vikunja updates.
+
+## Commit Format
+
+Use **conventional commits** on feature branches:
+
+```
+feat: add new command
+fix: resolve timeout issue
+chore: update dependencies
+docs: improve README
+```
+
+Allowed types: `feat`, `fix`, `chore`, `docs`, `style`, `refactor`, `perf`, `test`, `ci`, `build`, `revert`, `BREAKING CHANGE`.
+
+**Do NOT** include the `GRM-N:` prefix in commit messages on feature branches — it is added automatically during squash merge.
+
+## PR Workflow
+
+1. Create a branch `GRM-N` or `GRM-N-brief-description` from `master`
+2. Make changes, committing with conventional format
+3. Push and open a PR against `master`
+4. CI runs lint, unit tests, and molecule tests
+5. When all checks pass, add the `ready-to-merge` label
+6. The auto-merge workflow squash-merges with message `GRM-N: <PR title>`
+7. The post-merge workflow updates the Vikunja task
+
+## Local Testing
+
+```bash
+make test-all    # Runs pytest-cov + molecule
+make lint-all    # Runs ruff, pyright, ansible-lint, checkmake
+make pytest-cov  # Unit tests with 100% coverage enforcement
+make molecule    # All 7 molecule scenarios
+```
+
+## Code Quality
+
+- **ruff**: Line length 120
+- **pyright**: Strict mode
+- **Test coverage**: 100% required
+- **ansible-lint**: For all Ansible content
diff --git a/README.md b/README.md
index 0910138..2f5d213 100644
--- a/README.md
+++ b/README.md
@@ -6,6 +6,15 @@ By default, runners are deployed as **Docker containers** using the official `gi
 
 > **Pronunciation note:** GRM is short for *Gitea Runner Manager*, but say it like **ГРЪМ** (roughly "GRUM" in Latin letters) — the Bulgarian word for **thunder**. Wherever there are clouds, there may be thunders. This is an open-source project from **Oblachno** (облачно means *cloudy* in Bulgarian).
 
+[![CI](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions/workflows/ci.yml/badge.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
+
+## Commit Convention & Branch Naming
+
+This project uses **conventional commits** and **GRM-N branch prefixes**. See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+- Branches: `GRM-N` or `GRM-N-brief-description` (required for CI automation)
+- Commits: `feat:`, `fix:`, `chore:`, etc. (no `GRM-N:` prefix on feature branches)
+
 ## Features
 
 - **Simple and focused** — no unnecessary features.
diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md
new file mode 100644
index 0000000..2dbabc4
--- /dev/null
+++ b/TROUBLESHOOTING.md
@@ -0,0 +1,12 @@
+# Troubleshooting
+
+| Symptom | Likely Cause | Solution |
+|---------|-------------|----------|
+| Pre-commit rejects commit message | Missing conventional format or GRM-N prefix present | Use `feat: description` format without `GRM-N:` |
+| `make molecule` fails with `runner_name is undefined` | Verify playbook missing variable | Fixed in Phase 1.1; ensure you're on latest master |
+| CI molecule job fails | Docker not available on runner host | Ensure Gitea runner host has Docker installed and running |
+| Auto-merge doesn't trigger | Label not exactly `ready-to-merge` or CI checks not all green | Verify label spelling; check CI status |
+| Vikunja task not updated after merge | VIKUNJA_TOKEN expired or task ID missing from commit | Regenerate token; verify merge commit has `GRM-N:` prefix |
+| Post-merge can't find Vikunja task | Task not in project 6 or identifier mismatch | Verify task exists in Vikunja project 6 with correct identifier |
+| `make pytest-cov` fails | Coverage below 100% | Add tests for new code paths |
+| `scripts/configure_repo.py` fails | GITEA_ADMIN_TOKEN missing or invalid | Set token with repo admin scope and re-run |