Skip to content

Latest commit

 

History

History
319 lines (226 loc) · 5.04 KB

CONTRIBUTING.md

File metadata and controls

319 lines (226 loc) · 5.04 KB

Contributing to arctl

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

Getting Started

  1. Fork the repository
  2. Clone your fork: git clone https://github.com/YOUR_USERNAME/agentregistry.git
  3. Add upstream remote: git remote add upstream https://github.com/agentregistry-dev/agentregistry.git
  4. Create a branch: git checkout -b feature/my-feature

Development Setup

Prerequisites

  • Go 1.22 or later
  • Node.js 18 or later
  • npm or yarn
  • make (optional but recommended)

Initial Setup

# Run the setup script
./setup.sh

# Or manually:
cd ui && npm install && cd ..
make build

Development Workflow

Working on the CLI

# Make changes to cmd/*.go or internal/**/*.go

# Build quickly (without UI rebuild)
go build -o bin/arctl main.go

# Test your changes
./bin/arctl <command>

# Run tests
go test ./...

Working on the UI

# Start development server with hot reload
make dev-ui
# Opens at http://localhost:3000

# Make changes to ui/app/**/*.tsx

# When ready to test with CLI:
make build-ui
make build-cli
./bin/arctl ui

Working on Both

# Terminal 1: UI dev server
make dev-ui

# Terminal 2: CLI development
go build -o bin/arctl main.go
./bin/arctl <command>

# When ready for integration test:
make build
./bin/arctl ui

Code Style

Go

  • Follow standard Go conventions
  • Use gofmt for formatting
  • Use golangci-lint for linting
  • Write meaningful comments for exported functions
  • Keep functions small and focused
# Format code
make fmt

# Run linter
make lint

TypeScript/React

  • Follow Next.js and React best practices
  • Use TypeScript for type safety
  • Use functional components with hooks
  • Keep components small and reusable
# Lint UI code
cd ui
npm run lint

Testing

Go Tests

# Run all tests
go test ./...

# Run with coverage
go test -cover ./...

# Run specific test
go test -run TestFunctionName ./...

UI Tests

cd ui
npm test

Adding New Features

New CLI Command

  1. Create cmd/mycommand.go:
package cmd

import (
    "fmt"
    "github.com/spf13/cobra"
)

var myCmd = &cobra.Command{
    Use:   "my-command",
    Short: "Description",
    Run: func(cmd *cobra.Command, args []string) {
        fmt.Println("Implementation")
    },
}

func init() {
    rootCmd.AddCommand(myCmd)
}
  1. Add tests
  2. Update documentation
  3. Build and test

New API Endpoint

  1. Add handler in internal/api/server.go:
func getMyData(c *gin.Context) {
    data, err := database.GetMyData()
    if err != nil {
        c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
        return
    }
    c.JSON(http.StatusOK, data)
}
  1. Register route:
api.GET("/my-data", getMyData)
  1. Add database methods
  2. Add tests

New UI Component

  1. Create component in ui/components/:
import { Card } from "@/components/ui/card"

export function MyComponent() {
  return <Card>Content</Card>
}
  1. Use in page:
import { MyComponent } from "@/components/MyComponent"

export default function Page() {
  return <MyComponent />
}
  1. Build and test

Database Changes

When adding/modifying database schema:

  1. Update schema in internal/database/database.go
  2. Add/update models in internal/models/models.go
  3. Add migration logic if needed
  4. Update query methods
  5. Test with fresh database

Documentation

Update documentation when adding features:

  • README.md - Overview and commands
  • Inline code comments

Commit Messages

Follow conventional commits:

type(scope): subject

body

footer

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation
  • style: Formatting
  • refactor: Code restructuring
  • test: Tests
  • chore: Maintenance

Examples:

feat(cli): add search command
fix(api): handle empty registry list
docs: update quickstart guide
refactor(db): simplify query methods

Pull Request Process

  1. Update documentation
  2. Add/update tests
  3. Ensure CI passes
  4. Include a release-note block in your PR description (see PR template)
  5. Request review

PR Checklist

  • Code follows style guidelines
  • Tests added/updated
  • Documentation updated
  • CI passes
  • Commits are clean and meaningful

Building for Release

Maintainers should follow the complete release process. Releases are built and published by GitHub Actions from an annotated SemVer tag on main.

Common Issues

Go Module Issues

go mod tidy

UI Build Failures

cd ui
rm -rf node_modules package-lock.json .next
npm install
npm run build

Embed Issues

Ensure UI is built before Go build:

make build-ui
make build-cli

Getting Help

  • Open an issue for bugs
  • Start a discussion for questions
  • Join our Discord (if available)

Code of Conduct

  • Be respectful and inclusive
  • Welcome newcomers
  • Give constructive feedback
  • Focus on what's best for the project

Thank you for contributing! 🎉