Contribution Workflow

Guidelines for contributing to Ignis - help us maintain quality and streamline the process.

Git Branching Strategy

main (production)
  ↑
  │ merge only from develop
  │
develop (staging)
  ↑
  │ PRs target here
  │
feature/*, fix/*, docs/* (your work)

Important:

• ✅ Create PRs to develop branch
• ❌ Do NOT create PRs to main branch
• main only accepts merges from develop
• Releases are tagged in git (e.g., v1.0.0)

1. Setup

Quick start:

# 1. Fork the repository on GitHub

# 2. Clone your fork
git clone https://github.com/YOUR_USERNAME/ignis.git
cd ignis

# 3. Install dependencies (this also runs force-update to fetch latest from NPM)
make install
# Or: bun install

# 4. Add upstream remote
git remote add upstream https://github.com/VENIZIA-AI/ignis.git

Package Build Order

Ignis is a monorepo with interdependent packages. Understanding the dependency chain is critical for development:

dev-configs → inversion → helpers → boot → core
     ↓            ↓           ↓        ↓      ↓
  @venizia/   @venizia/   @venizia/  @venizia/  @venizia/
  dev-configs ignis-      ignis-     ignis-     ignis
              inversion   helpers    boot       (core)

Dependency meanings:

Package	Depends On	Purpose
dev-configs	-	Shared ESLint, TypeScript configs
inversion	dev-configs	IoC container, DI primitives
helpers	inversion	Utilities, loggers, crypto
boot	helpers	Application bootstrapping
core	boot	Full framework (controllers, repos, etc.)

Why this matters:

• If you modify helpers, you must rebuild boot and core
• If you modify inversion, you must rebuild helpers, boot, and core
• The Makefile handles this automatically with dependencies

Makefile Commands

The project uses a Makefile for common development tasks:

Command	Description
make install	Install dependencies and force-update from NPM
make update	Force update all packages from NPM registry
make build	Rebuild all packages in correct order
make clean	Clean build artifacts from all packages
make lint	Lint all packages
make help	Show all available commands

Individual package builds (dependencies are automatically resolved):

make core          # Build @venizia/ignis (builds dev-configs → inversion → helpers → boot → core)
make boot          # Build @venizia/ignis-boot (builds dev-configs → inversion → helpers → boot)
make helpers       # Build @venizia/ignis-helpers (builds dev-configs → inversion → helpers)
make inversion     # Build @venizia/ignis-inversion (builds dev-configs → inversion)
make dev-configs   # Build @venizia/dev-configs only
make docs          # Build VitePress documentation (independent)
make docs-mcp      # Build MCP documentation server

Force update individual packages:

make update-core
make update-boot
make update-helpers
make update-inversion
make update-dev-configs
make update-docs

2. Development Workflow

Step 1: Create Branch

# Sync with upstream
git fetch upstream
git checkout main
git merge upstream/main

# Create feature branch
git checkout -b feature/your-feature-name

Branch naming:

Type	Format	Example
Feature	feature/description	feature/add-redis-cache
Bug fix	fix/description	fix/auth-token-expiry
Docs	docs/description	docs/update-quickstart
Chore	chore/description	chore/upgrade-deps

Step 2: Make Changes

Checklist:

• ✅ Follow Code Style Standards
• ✅ Follow Architectural Patterns
• ✅ Add tests for new features/fixes
• ✅ Update docs in packages/docs/wiki if needed

Step 3: Commit

Use Conventional Commits:

# Examples
git commit -m "feat: add Redis caching helper"
git commit -m "fix: correct JWT token validation"
git commit -m "docs: update controller examples"
git commit -m "chore: upgrade Hono to v4.0"

Commit types:

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation only
• chore: - Maintenance (deps, config)
• refactor: - Code restructuring
• test: - Adding tests

Step 4: Validate

# Lint and format (from root)
make lint
# Or: bun run lint:fix

# Build all packages
make build
# Or: bun run build

# Run tests
bun run test

3. Submit Pull Request

# Push your branch
git push origin feature/your-feature-name

PR Guidelines:

Item	Description
Title	Use conventional commit format: feat: add Redis caching
Description	Explain what and why (not just how)
Link issues	Reference related issues: Closes #123
Screenshots	Include for UI changes
Breaking changes	Clearly mark and explain

PR Checklist:

• ✅ All tests pass
• ✅ Code is linted and formatted
• ✅ Documentation updated
• ✅ Commit messages follow conventions
• ✅ Branch is up-to-date with main

4. Review Process

What to expect:

1. Maintainer reviews your PR (usually within 2-3 days)
2. Feedback or change requests may be provided
3. Address feedback and push updates
4. Once approved, maintainer merges to main

Responding to feedback:

# Make requested changes
git add .
git commit -m "fix: address review feedback"
git push origin feature/your-feature-name

Thank you for contributing to Ignis! 🎉