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