89 lines
2.5 KiB
Markdown
89 lines
2.5 KiB
Markdown
# 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.
|