quickstart/CONTRIBUTING.md

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

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

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

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: 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	Main production app
sdl-framework	Development framework
engineering-standards	Standards content
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.