mates-infra/docs/contributing.md

🤝 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:

# 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.