Contributing

⚠️ Work in Progress: This documentation is currently being developed and may be incomplete or subject to change.

Overview

Thank you for your interest in contributing to the Antimetal System Agent! This guide will help you get started with contributing to the project, whether you're fixing bugs, adding features, improving documentation, or helping in other ways.

Getting Started

Prerequisites

• Go 1.21+ installed
• Docker for building images
• Kubernetes cluster for testing (KIND/Minikube works)
• Git for version control

Development Setup

1. Fork and clone the repository

   git clone https://github.com/YOUR-USERNAME/system-agent.git
   cd system-agent
   

2. Install dependencies

   go mod download
   

3. Run tests

   make test
   

4. Build the agent

   make build
   

Contributing Process

1. Find an Issue

• Check existing issues
• Look for good first issue labels for beginner-friendly tasks
• Comment on the issue to claim it
• Ask questions if requirements are unclear

2. Create a Branch

git checkout -b feature/your-feature-name
# or
git checkout -b fix/issue-description

3. Make Your Changes

• Write clean, documented code
• Follow existing code patterns
• Add tests for new functionality
• Update documentation as needed

4. Testing

Run all tests before submitting:

# Unit tests
make test

# Integration tests
make test-integration

# Lint checks
make lint

# All checks
make check

5. Commit Your Changes

Follow conventional commit format:

git commit -m "feat: add new memory collector metric"
git commit -m "fix: handle nil pointer in cpu collector"
git commit -m "docs: update configuration guide"

Commit types:

• feat: New feature
• fix: Bug fix
• docs: Documentation only
• test: Test additions/changes
• refactor: Code refactoring
• chore: Maintenance tasks

6. Submit Pull Request

1. Push your branch

   git push origin feature/your-feature-name
   

2. Create PR on GitHub

3. Fill out PR template

4. Link related issues

5. Wait for review

Code Guidelines

Go Code Style

Follow standard Go conventions:

// Package collectors implements performance metric collectors
package collectors

import (
    "context"
    "fmt"
    
    "github.com/antimetal/system-agent/pkg/performance"
)

// CPUCollector collects CPU metrics from /proc/stat
type CPUCollector struct {
    logger Logger
    config CollectionConfig
}

// Collect gathers CPU statistics
func (c *CPUCollector) Collect(ctx context.Context) (any, error) {
    // Implementation
}

Best Practices

1. Error Handling

   if err != nil {
       return nil, fmt.Errorf("failed to read /proc/stat: %w", err)
   }
   

2. Context Usage

   select {
   case <-ctx.Done():
       return nil, ctx.Err()
   default:
       // Continue processing
   }
   

3. Resource Cleanup

   file, err := os.Open(path)
   if err != nil {
       return nil, err
   }
   defer file.Close()
   

4. Logging

   logger.Info("Starting collection", "collector", c.Name())
   logger.Error("Collection failed", "error", err)
   

Adding New Collectors

To add a new performance collector:

1. Define the metric type in pkg/performance/types.go:

   const MetricTypeMyNewMetric MetricType = "my_new_metric"
   

2. Create collector in pkg/performance/collectors/my_new_collector.go:

   type MyNewCollector struct {
       logger Logger
       config CollectionConfig
   }
   
   func (c *MyNewCollector) Name() string {
       return string(performance.MetricTypeMyNewMetric)
   }
   
   func (c *MyNewCollector) Collect(ctx context.Context) (any, error) {
       // Implementation
   }
   

3. Register collector in pkg/performance/registry.go:

   performance.Register(
       performance.MetricTypeMyNewMetric,
       performance.PartialNewContinuousPointCollector(NewMyNewCollector),
   )
   

4. Add tests in pkg/performance/collectors/my_new_collector_test.go

5. Update documentation:

   • Create wiki/My-New-Collector.md
   • Add to wiki/Performance-Collectors.md
   • Update wiki/Home.md navigation

Testing Guidelines

Unit Tests

func TestCPUCollector_Collect(t *testing.T) {
    tests := []struct {
        name    string
        setup   func()
        want    any
        wantErr bool
    }{
        {
            name: "successful collection",
            setup: func() {
                // Test setup
            },
            want: &CPUStats{...},
            wantErr: false,
        },
    }
    
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            // Test implementation
        })
    }
}

Integration Tests

Place in _test packages for proper isolation:

package collectors_test

import (
    "testing"
    "github.com/antimetal/system-agent/pkg/performance/collectors"
)

Documentation

Code Documentation

• Document all exported types and functions
• Include examples for complex functionality
• Explain non-obvious implementation details

Wiki Documentation

When adding features, update the wiki:

1. Create new pages for new collectors/features
2. Update existing pages with new options
3. Add examples and use cases
4. Include troubleshooting tips

Release Process

1. Version Tagging

   • Follow semantic versioning (v1.2.3)
   • Create annotated tags
   • Include changelog

2. Release Notes

   • List all changes
   • Credit contributors
   • Include upgrade instructions

Getting Help

• Discord: Join our community server
• GitHub Discussions: Ask questions
• Issues: Report bugs or request features
• Email: [email protected]

Code of Conduct

• Be respectful and inclusive
• Welcome newcomers
• Provide constructive feedback
• Focus on what's best for the project
• Help others learn and grow

Recognition

Contributors are recognized in:

• Release notes
• CONTRIBUTORS.md file
• Project documentation
• Community highlights

Thank you for contributing to Antimetal System Agent!