Thank you for your interest in contributing to arctl! This document provides guidelines and instructions for contributing.
- Fork the repository
- Clone your fork:
git clone https://github.com/YOUR_USERNAME/agentregistry.git - Add upstream remote:
git remote add upstream https://github.com/agentregistry-dev/agentregistry.git - Create a branch:
git checkout -b feature/my-feature
- Go 1.22 or later
- Node.js 18 or later
- npm or yarn
- make (optional but recommended)
# Run the setup script
./setup.sh
# Or manually:
cd ui && npm install && cd ..
make build# 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 ./...# 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# 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- Follow standard Go conventions
- Use
gofmtfor formatting - Use
golangci-lintfor linting - Write meaningful comments for exported functions
- Keep functions small and focused
# Format code
make fmt
# Run linter
make lint- 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# Run all tests
go test ./...
# Run with coverage
go test -cover ./...
# Run specific test
go test -run TestFunctionName ./...cd ui
npm test- 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)
}- Add tests
- Update documentation
- Build and test
- 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)
}- Register route:
api.GET("/my-data", getMyData)- Add database methods
- Add tests
- Create component in
ui/components/:
import { Card } from "@/components/ui/card"
export function MyComponent() {
return <Card>Content</Card>
}- Use in page:
import { MyComponent } from "@/components/MyComponent"
export default function Page() {
return <MyComponent />
}- Build and test
When adding/modifying database schema:
- Update schema in
internal/database/database.go - Add/update models in
internal/models/models.go - Add migration logic if needed
- Update query methods
- Test with fresh database
Update documentation when adding features:
README.md- Overview and commands- Inline code comments
Follow conventional commits:
type(scope): subject
body
footer
Types:
feat: New featurefix: Bug fixdocs: Documentationstyle: Formattingrefactor: Code restructuringtest: Testschore: Maintenance
Examples:
feat(cli): add search command
fix(api): handle empty registry list
docs: update quickstart guide
refactor(db): simplify query methods
- Update documentation
- Add/update tests
- Ensure CI passes
- Include a
release-noteblock in your PR description (see PR template) - Request review
- Code follows style guidelines
- Tests added/updated
- Documentation updated
- CI passes
- Commits are clean and meaningful
Maintainers should follow the complete release process.
Releases are built and published by GitHub Actions from an annotated SemVer
tag on main.
go mod tidycd ui
rm -rf node_modules package-lock.json .next
npm install
npm run buildEnsure UI is built before Go build:
make build-ui
make build-cli- Open an issue for bugs
- Start a discussion for questions
- Join our Discord (if available)
- Be respectful and inclusive
- Welcome newcomers
- Give constructive feedback
- Focus on what's best for the project
Thank you for contributing! 🎉