# Contributing to Railiance

Welcome, and thank you for contributing!  
Railiance is an opinionated Infrastructure-as-Code framework.  
To keep it clean, secure, and reproducible, please follow these guidelines.

---

## 📦 Repository Hygiene

- **Do NOT commit secrets**  
  Never commit tokens, passwords, vault keys, or private inventories.  
  Use `~/.railiance_gitea.conf` for local config.

- **Line endings**  
  - Always **LF (`\n`)**, never CRLF.  
  - Enforced via `.editorconfig` and `.gitattributes`.

- **Ignore local junk**  
  Check `.gitignore` — if a file is listed there, it must not be versioned.

---

## 🛠 Code Style

- **YAML / Ansible / K8s manifests:** 2 spaces indentation.  
- **Python:** 4 spaces indentation, PEP8 where reasonable.  
- **Shell scripts:** 2 spaces, `set -euo pipefail`, and `#!/usr/bin/env bash`.

- Keep scripts **idempotent** (safe to re-run without breaking).  
- Add comments generously — this repo is also documentation.

---

## 🔄 Workflow

1. **Branching**  
   - Use feature branches: `feature/<topic>`  
   - Bugfixes: `fix/<topic>`  
   - Infrastructure experiments: `exp/<topic>`

2. **Commits**  
   - Keep them small, focused, and with clear messages.  
   - Prefix optional: `feat:`, `fix:`, `chore:`, `docs:`, `test:`.

3. **Pull Requests**  
   - Every change should come via PR, even small fixes.  
   - PR description: what, why, and how tested.  
   - At least one review before merge (self-review counts if solo).

---

## ✅ Testing

- Each automation step should be verifiable with a test (`tests/`).  
- Run tests locally before pushing.  
- If you add a new playbook or Helm chart, add or update a corresponding test.

---

## 🤖 AI & Automation

Railiance assumes **AI-first workflows**.  
- Scripts should provide clear outputs that can be parsed by agents.  
- Logs must be machine- and human-readable.  
- Favor **convention over configuration** — less choice, more clarity.

---

## 🌱 Philosophy

- **Convention over configuration**: prefer defaults.  
- **Don’t repeat yourself**: centralize config.  
- **Calm ops**: keep infra resilient and predictable.  
- **Self-reliance**: everything must bootstrap from bare metal + this repo.

---

## 🚫 What Not to Do

- Don’t hard-code IPs, tokens, or passwords.  
- Don’t commit binaries (except intentionally versioned Helm charts).  
- Don’t bypass review by committing directly to `main`.

---

✌️ Happy hacking!  
Let’s keep Railiance simple, reproducible, and fun.