From df06dfc5e389e5077f66147e020db17b3e03b20a Mon Sep 17 00:00:00 2001
From: Claude Agent <claude@openclaw.dev>
Date: Wed, 24 Jun 2026 03:04:57 +0200
Subject: [PATCH] docs: add CONTRIBUTING.md (Phase 5 roadmap item)

---
 CONTRIBUTING.md | 135 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 135 insertions(+)
 create mode 100644 CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..10d9c3a
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,135 @@
+# Contributing to d0a1 Quickstart
+
+Thanks for your interest in contributing! d0a1 Quickstart is a one-command local AI setup — Ollama + Open WebUI in Docker, no cloud, no API keys. This guide covers how to make changes and submit them.
+
+---
+
+## Repository Layout
+
+```
+deploy.sh          ← One-command deployment script (bash)
+docker-compose.yml ← Docker Compose stack (Ollama + Open WebUI)
+.env.example       ← Template configuration file
+.gitattributes     ← LF normalization (prevents CRLF issues on WSL)
+.gitignore         ← Git ignore rules
+README.md          ← User-facing documentation (Spanish)
+LICENSE            ← MIT license
+CONTRIBUTING.md    ← You are here
+```
+
+---
+
+## Development Workflow
+
+### 1. Clone and branch
+
+```bash
+git clone https://git.d0a1.es/monyi/quickstart.git
+cd quickstart
+git checkout -b feat/your-feature
+```
+
+### 2. Make changes
+
+The repo is a pure infrastructure project — no build step, no dependencies. Edit `deploy.sh`, `docker-compose.yml`, `.env.example`, or `README.md` directly.
+
+### 3. Test locally
+
+```bash
+cp .env.example .env
+# Edit .env if you want non-default ports or models
+./deploy.sh
+```
+
+Verify:
+- Both containers start (`docker compose ps`)
+- Open WebUI loads at `http://localhost:3000`
+- Ollama responds at `http://localhost:11434`
+- The default model downloads successfully
+- `deploy.sh` exits with code 0
+
+### 4. Commit and push
+
+```bash
+git add .
+git commit -m "fix: short description of your change"
+git push origin feat/your-feature
+```
+
+### 5. Create a Pull Request
+
+Use the Gitea web UI or API. Reference any related issues in the PR body (e.g., `closes #2`).
+
+---
+
+## Code Style
+
+### Shell (deploy.sh)
+
+- Use `const`/`let` equivalents — no mutable global state without good reason
+- `set -euo pipefail` is already in place; maintain it
+- LF line endings only (no CRLF) — `.gitattributes` enforces this
+- Use `printf` instead of `echo` for portability (already established)
+- Quote all variable expansions: `"$VAR"`, not `$VAR`
+- Use `command -v` for binary checks, not `which`
+
+### Docker Compose
+
+- Pin image versions explicitly (never use `:latest`)
+- Use named volumes for persistent data
+- Document any new environment variables in both `.env.example` and `README.md`
+
+### Documentation
+
+- README is in Spanish (user-facing); CONTRIBUTING.md is in English (contributor-facing)
+- Keep the configuration table in README.md in sync with `.env.example`
+- Use Markdown tables for structured data
+
+### Commits
+
+- Use [Conventional Commits](https://www.conventionalcommits.org/): `feat:`, `fix:`, `docs:`, `chore:`, `refactor:`
+- Keep the subject line under 72 characters
+- Reference issues in the body when applicable
+
+---
+
+## Testing
+
+There is no automated test suite. Manual verification before submitting a PR:
+
+1. Run `./deploy.sh` on a clean environment (remove existing containers/volumes)
+2. Verify both services come up healthy
+3. Test the `.env.example` → `.env` copy path works
+4. If you changed `docker-compose.yml`, verify `docker compose config` validates
+5. If you changed `deploy.sh`, test on both Linux and WSL2 if possible
+
+---
+
+## Ecosystem Context
+
+d0a1 Quickstart is the entry point to the d0a1 ecosystem:
+
+| Repository | Role |
+|---|---|
+| [storeroom-os](https://git.d0a1.es/d0a1/storeroom-os) | Main production app |
+| [sdl-framework](https://git.d0a1.es/d0a1/sdl-framework) | Development framework |
+| [engineering-standards](https://git.d0a1.es/d0a1/engineering-standards) | Standards content |
+| [quickstart](https://git.d0a1.es/monyi/quickstart) | This repo — local AI quickstart |
+
+---
+
+## Reporting Issues
+
+Open an issue at https://git.d0a1.es/monyi/quickstart/issues with:
+
+1. A clear title describing the problem or feature
+2. Steps to reproduce (for bugs)
+3. Expected vs actual behavior
+4. OS and Docker version information
+5. Relevant logs (`docker compose logs`)
+
+---
+
+## License
+
+By contributing, you agree that your contributions are licensed under the MIT license.