Skip to content

Latest commit

 

History

History
121 lines (85 loc) · 2.96 KB

CONTRIBUTING.md

File metadata and controls

121 lines (85 loc) · 2.96 KB

Contributing to Canon

Thank you for your interest in contributing to Canon! This document provides guidelines and instructions for contributing.

Development Setup

Prerequisites

  • Go 1.22 or later
  • Node.js 18+ (for running generated TypeScript)
  • npm (for TypeScript dependencies)

Getting Started

# Clone the repository
git clone https://github.com/WarforgeTech/canon.git
cd canon

# Build the CLI
make build

# Run tests
make test

# Verify everything works
./bin/canon build examples/hello/hello.canon.json

How to Contribute

Reporting Bugs

  1. Check if the bug has already been reported in Issues
  2. If not, create a new issue using the bug report template
  3. Include steps to reproduce, expected behavior, and actual behavior

Suggesting Features

  1. Check existing issues and discussions for similar ideas
  2. Create a new issue using the feature request template
  3. Describe the use case and why this feature would be valuable

Submitting Code

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes
  4. Run tests (make test)
  5. Commit your changes with a clear message
  6. Push to your fork
  7. Open a Pull Request

Code Style

Go Code

  • Follow standard Go conventions
  • Run go fmt before committing
  • Add tests for new functionality
  • Keep functions focused and well-documented

TypeScript (runtime-ts/)

  • Use TypeScript strict mode
  • Document public APIs with JSDoc comments

Testing

Running Tests

# Run all Go tests
make test

# Run tests with verbose output
go test -v ./...

# Run a specific test
go test -v ./pkg/validate -run TestTypechecking

Writing Tests

  • Add unit tests for new functions in *_test.go files
  • Add integration tests for CLI commands in cmd/canon/integration_test.go
  • For Canon programs, add golden tests in the .canon.json file

Pull Request Guidelines

  • Keep PRs focused on a single change
  • Update documentation if needed
  • Ensure all tests pass
  • Add tests for new functionality
  • Reference related issues in the PR description

Project Structure

canon/
├── cmd/canon/       # CLI commands
├── pkg/
│   ├── ir/          # Intermediate representation types
│   ├── validate/    # Validation (schema, types, effects)
│   ├── codegen/     # Code generation (TypeScript)
│   ├── policy/      # OPA/Rego policy engine
│   └── testing/     # Test runner
├── runtime-ts/      # TypeScript runtime library
├── schemas/         # JSON Schema definitions
├── policies/        # Default Rego policies
└── examples/        # Example Canon programs

Questions?

License

By contributing, you agree that your contributions will be licensed under the MIT License.