Claude Agent
136 lines
3.9 KiB
Markdown
136 lines
3.9 KiB
Markdown
# 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.
|