RAGed

Contributing

How to develop, test, and submit changes to raged.

Development Setup

Prerequisites

• Node.js 20+
• Docker and Docker Compose
• Git

First-Time Setup

# Clone the repo
git clone https://github.com/<org>/raged.git
cd raged

# Start infrastructure
docker compose up -d

# Pull embedding model
curl http://localhost:11434/api/pull -d '{"name":"nomic-embed-text"}'

# Install and build both packages
cd api && npm install && npm run build && cd ..
cd cli && npm install && npm run build && cd ..

Development Workflow

flowchart LR
    B[Create branch] --> C[Write failing test]
    C --> I[Implement]
    I --> T[Run tests]
    T --> P{Pass?}
    P -->|No| I
    P -->|Yes| CO[Commit]
    CO --> PR[Open PR]

    style C fill:#fff3e0
    style CO fill:#c8e6c9

Branch Naming

feat/<short-description>    # New features
fix/<short-description>     # Bug fixes
docs/<short-description>    # Documentation
refactor/<short-description> # Code improvements
test/<short-description>    # Test additions

Commit Messages

Follow Conventional Commits:

feat: add query caching for repeated searches
fix: handle empty file during indexing
docs: add Mermaid diagram to architecture doc
refactor: extract embedding client interface
test: add unit tests for chunking module
chore: update dependencies

Keep the first line under 72 characters. Add a body for complex changes.

Pull Requests

1. Branch from main
2. Keep PRs focused — one logical change per PR
3. Ensure CI passes (build + lint)
4. Write a clear description: what changed and why
5. Link related issues if applicable

CI Pipeline Layout

The CI workflow is in .github/workflows/ci.yaml. Use Actions → Run workflow to manually trigger .github/workflows/pages.yml when needed.

• Node quality jobs use matrices for api and cli (build, lint)
• Worker quality jobs use the worker-ci matrix (test, lint)
• Docker builds are split by concern:
  • docker-build-node builds API and indexer images via matrix
  • docker-build-worker builds the worker image separately

This structure keeps jobs focused and reduces duplication.

Release and Publishing

Docker images are automatically published to GitHub Container Registry (GHCR) via .github/workflows/publish-images.yaml.

Publishing Triggers

Manual Dispatch:

• Triggered from the Actions UI or gh workflow run
• Useful for validating build and publish behavior without pushing a new commit

Main Branch Pushes:

• Triggered on every push to main
• Creates tags: main and sha-<commit-short-sha>
• Example: ghcr.io/mfittko/raged-api:main, ghcr.io/mfittko/raged-api:sha-abc1234

Version Tag Pushes:

• Triggered on tags matching v*.*.* (e.g., v0.6.0)
• Creates semantic version tags: <version>, <major>.<minor>, <major>, and latest
• Example tag v0.6.0 produces:
  • ghcr.io/mfittko/raged-api:0.6.0
  • ghcr.io/mfittko/raged-api:0.6
  • ghcr.io/mfittko/raged-api:0
  • ghcr.io/mfittko/raged-api:latest

Published Images

All three core components are published:

• API: ghcr.io/mfittko/raged-api
• CLI/Indexer: ghcr.io/mfittko/raged
• Worker: ghcr.io/mfittko/raged-worker

Creating a Release

To publish a new version:

# Create tag + GitHub release notes from CHANGELOG.md
export OPENAI_API_KEY=your_key_here
scripts/create-release.sh v0.6.0

# Or auto-increment the next stable semver tag
scripts/create-release.sh --bump patch

# Dry-run notes generation without pushing tag/release
scripts/create-release.sh v0.6.0 --dry-run

The script will:

• generate release title/body with OpenAI using CHANGELOG.md
• create and push an annotated tag
• create a GitHub release with the generated notes

Release Automation Gap

Target direction: release automatically from main after merge.

Current gap: we do not yet have remote-deployment smoke tests to validate the newly released image in an environment before finalizing a stable release. Until that exists, releases remain script-driven.

When smoke-test infrastructure is available, automate release creation with a main-triggered workflow that:

• builds and publishes candidate images
• runs post-deploy smoke tests against a remote environment
• creates the final stable tag and GitHub release only if smoke tests pass

The publish-images workflow will automatically build and publish all three images with multi-arch support (linux/amd64, linux/arm64) and semantic tags (0.6.0, 0.6, 0, latest).

Note:

• Git tags use the v prefix (e.g., v0.6.0), but Docker image tags do not (e.g., 0.6.0). Always reference images without the v prefix in Helm values and deployment configurations.
• The latest tag is updated only on version tag pushes. Main branch pushes publish main and sha-* tags for development builds.

Image Features

• Multi-architecture: All images support linux/amd64 and linux/arm64
• OCI labels: Images include standard metadata (title, description, source, version)
• Build cache: GitHub Actions cache is used to speed up subsequent builds
• Least-privilege: Uses GitHub’s GITHUB_TOKEN with packages: write permission

Worker Dependency Files

Worker dependencies are split by purpose:

• worker/requirements.txt → runtime dependencies
• worker/requirements-test.txt → test dependencies (extends runtime)
• worker/requirements-lint.txt → lint-only dependencies

Pinned lock files are committed and used in CI and Docker builds:

• worker/requirements.lock
• worker/requirements-test.lock
• worker/requirements-lint.lock

Refreshing Worker Lock Files

When changing worker dependency inputs, regenerate lock files in worker/:

cd worker
python3 -m pip install pip-tools
python3 -m piptools compile requirements.txt -o requirements.lock
python3 -m piptools compile requirements-test.txt -o requirements-test.lock
python3 -m piptools compile requirements-lint.txt -o requirements-lint.lock

Commit both the changed input file(s) and generated lock file(s) in the same PR.

Project Structure

raged/
├── api/          → Fastify RAG API (see api/AGENTS.md)
├── cli/          → CLI indexer tool (see cli/AGENTS.md)
├── chart/        → Helm chart (see chart/AGENTS.md)
├── docs/         → Documentation (see docs/AGENTS.md)
├── .claude/      → Claude Code skill definitions
├── .github/      → CI/CD workflows
└── AGENTS.md     → Project-wide coding principles

Code Style

• TypeScript with strict mode
• ES modules (import/export, not require)
• No any in new code
• Named exports only (no default exports)

See AGENTS.md for the full set of conventions.

Adding a New API Endpoint

1. Add the route in api/src/server.ts
2. Add JSON Schema validation for input
3. Delegate logic to a service module (not inline in the handler)
4. Update docs/09-api-reference.md

Adding a New CLI Command

1. Add the command handler in cli/src/index.ts
2. Update the usage() function with all flags
3. Update docs/03-cli.md

This site is open source. Improve this page.