Contributing to ADL CLI

September 3, 2026 · View on GitHub

Thank you for your interest in contributing to the ADL CLI! This guide will help you get started with contributing to the project.

Code of Conduct
Getting Started
Development Setup
Contributing Guidelines
Submitting Changes
Adding Language Support
Testing
Documentation
Community

Code of Conduct

This project adheres to a code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainers.

Getting Started

Prerequisites

Go 1.26.7 or later
Git
Task (recommended for development tasks)
Docker (for testing container builds)

Development Setup

Fork the repository

# Fork the repo on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/adl-cli.git
cd adl-cli

Add upstream remote

git remote add upstream https://github.com/inference-gateway/adl-cli.git

Install dependencies
```
go mod download
```

Verify setup

# Run tests
task test

# Run linting
task lint

# Build the CLI
task build

Contributing Guidelines

Types of Contributions

We welcome several types of contributions:

🐛 Bug fixes - Fix issues in existing functionality
✨ New features - Add new capabilities to the CLI
🌍 Language support - Add support for new programming languages
📝 Documentation - Improve docs, examples, or help content
🧪 Tests - Add or improve test coverage
🔧 Tooling - Improve development tools and processes

Before You Start

Check existing issues - Look for existing issues or discussions about your idea
Create an issue - For new features or significant changes, create an issue first to discuss the approach
Small changes - For small bug fixes or documentation improvements, you can go directly to creating a PR

Coding Standards

Go Code Style

Follow standard Go conventions (gofmt, golint)
Use meaningful variable and function names
Add comments for exported functions and complex logic
Keep functions focused and reasonably sized
Use early returns to reduce nesting

Code Organization

Place new language templates in internal/templates/
Add new commands in cmd/
Use the existing error handling patterns
Follow the current project structure

Commit Messages

Use clear, descriptive commit messages:

feat: add TypeScript template support

- Add TypeScript template with Express.js framework
- Include enterprise features (auth, metrics, logging)
- Add corresponding tests and documentation

Fixes #123

Format: type: description

Types:

feat: - New feature
fix: - Bug fix
docs: - Documentation changes
test: - Adding or updating tests
refactor: - Code refactoring
chore: - Maintenance tasks

Submitting Changes

Pull Request Process

Create a feature branch

git checkout -b feature/your-feature-name

Make your changes
- Write code following our standards
- Add tests for new functionality
- Update documentation as needed

Test your changes

# Run all tests
task test

# Run linting
task lint

# Test with examples
task examples:test

Commit and push

git add .
git commit -m "feat: your descriptive commit message"
git push origin feature/your-feature-name

Create a Pull Request
- Use a clear title and description
- Reference any related issues
- Include screenshots for UI changes
- Add reviewers if you know who should review

Pull Request Requirements

Code follows project conventions
Tests pass (task test)
Linting passes (task lint)
Documentation updated (if applicable)
Examples work (if adding new functionality)
Commit messages are clear and descriptive

Adding Language Support

Adding support for a new programming language is a significant contribution. Here's how to approach it:

1. Planning

Create an issue to discuss the language addition
Define the scope and features for the language template
Identify the web framework and dependencies to use

2. Implementation Steps

A. Schema Updates

Update internal/schema/types.go to add language configuration:

type LanguageSpec struct {
    Go         *GoConfig         `yaml:"go,omitempty"`
    TypeScript *TypeScriptConfig `yaml:"typescript,omitempty"`
    Rust       *RustConfig       `yaml:"rust,omitempty"` // New language
    // ... other languages
}

type RustConfig struct {
    Edition     string `yaml:"edition"`     // e.g., "2021"
    Framework   string `yaml:"framework"`   // e.g., "axum"
    AsyncRuntime string `yaml:"runtime"`    // e.g., "tokio"
}

B. Template Creation

Create templates in internal/templates/:

// internal/templates/rust.go
package templates

func getRustTemplate() map[string]string {
    return map[string]string{
        "Cargo.toml":     rustCargoTemplate,
        "src/main.rs":    rustMainTemplate,
        "src/handlers.rs": rustHandlersTemplate,
        // ... other files
    }
}

const rustMainTemplate = `// Rust main template
use axum::{routing::post, Router};
// ... template content
`

C. Engine Updates

Update internal/templates/engine.go to handle the new language:

func (e *Engine) GetFiles() map[string]string {
    switch e.templateName {
    case "rust":
        return getRustTemplate()
    // ... existing cases
    }
}

D. Generator Updates

Update internal/generator/generator.go for language detection and validation.

3. Testing

Add tests for the new language
Create example ADL files in examples/
Test the template thoroughly
Verify generated code compiles and runs

4. Documentation

Update README.md roadmap
Add language-specific documentation
Include example ADL files
Document any language-specific features

Testing

Running Tests

# Run all tests
task test

# Run tests with coverage
task test:coverage

# Run specific tests
go test ./internal/generator -v

# Test examples
task examples:test

Writing Tests

Use table-driven tests when appropriate
Test both success and error cases
Mock external dependencies
Include integration tests for end-to-end flows

Example test structure:

func TestGenerator_GenerateRust(t *testing.T) {
    tests := []struct {
        name        string
        adlFile     string
        wantFiles   []string
        wantErr     bool
    }{
        {
            name:      "rust template",
            adlFile:   "testdata/rust-agent.yaml",
            wantFiles: []string{"Cargo.toml", "src/main.rs"},
            wantErr:   false,
        },
        // ... more test cases
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            // Test implementation
        })
    }
}