# 🤝 Contributing

> Jak přispívat do tohoto repozitáře.

## 📝 Pravidla

### Commit messages

Používej **Conventional Commits**:

- `feat:` – nová služba nebo funkce
- `fix:` – oprava chyby
- `docs:` – pouze dokumentace
- `chore:` – údržba, refactoring
- `style:` – formatting, bez funkční změny
- `refactor:` – přestavba kódu
- `test:` – přidání testů

Příklad: `feat(vaultwarden): přidat 2FA podporu`

### Branch naming

- `feature/<name>` – nová feature
- `fix/<name>` – bugfix
- `docs/<name>` – dokumentace

Příklad: `feature/audiobookshelf-metadata`

### Pull Request

1. Fork → branch → commit → push → PR
2. **Titulek PR** – krátký, výstižný
3. **Popis** – co, proč, jak
4. **Screenshoty** – pokud měníš UI/dokumentaci
5. **Testy** – pokud měníš Ansible playbooks

## 🏗 Struktura

```
repo/
├── docker-services/    # Každá služba v samostatném adresáři
├── install-scripts/     # Bash skripty pro nové servery
├── ansible/             # Playbooky + role
├── hermes-install/      # Hermes CLI setup
├── macos-setup/         # Homebrew + macOS defaults
├── home-nas-tools/      # Metadata (žádné binárky!)
└── docs/                # Architektura, bezpečnost
```

## ✅ Checklist pro novou službu

- [ ] `docker-services/<service>/docker-compose.yml` – generický, placeholders
- [ ] `docker-services/<service>/.env.example` – šablona env vars
- [ ] `docker-services/<service>/README.md` – dokumentace
- [ ] Aktualizován `docker-services/README.md` (tabulka)
- [ ] Aktualizován hlavní `README.md` (pokud je service klíčová)
- [ ] **Žádné citlivé údaje** v commitu

## 🔐 Bezpečnost

- ❌ **NEcommituj** hesla, API klíče, IP adresy serveru
- ❌ **NEcommituj** `~/.env` (je v `.gitignore`)
- ❌ **NEcommituj** SSH klíče
- ✅ **Vždy** používej `.env.example` jako šablonu
- ✅ **Vždy** testuj nové compose lokálně před commitem

## 🧪 Testování

Před commitem:

```bash
# Validace YAML
python3 -c "import yaml; yaml.safe_load(open('docker-services/<service>/docker-compose.yml'))"

# Validace compose (na serveru)
docker compose -f docker-services/<service>/docker-compose.yml config

# Syntax check bash
shellcheck install-scripts/<script>.sh

# Lint Ansible
ansible-lint ansible/playbooks/<playbook>.yml
```

## 📋 Verzování

- **Semver** – `MAJOR.MINOR.PATCH`
- **Tagy:** `v1.0.0`, `v1.1.0`, …
- **Release notes** – v GitHub/Gitea Releases

## 🐛 Hlášení chyb

Vytvoř **issue** v Gitea s:

1. **Název** – krátký popis
2. **Kroky k reprodukci** – co jsi udělal
3. **Očekávané chování** – co jsi čekal
4. **Skutečné chování** – co se stalo
5. **Verze** – `git describe` + verze OS

## 💡 Návrhy features

1. Otevři **issue** s labelem `enhancement`
2. Popiš use case – co chceš dělat
3. Jaké alternativy jsi zvážil
4. Jak to navrhuješ implementovat

## 📞 Kontakt

- **Issues:** Gitea
- **Email:** viz Gitea profil
- **Diskuze:** Gitea Discussions (pokud povoleno)

## 📜 Licence

Přispěním do tohoto repo souhlasíš s licencí [MIT](../LICENSE).