Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
237 lines (174 loc) · 5.81 KB

CONTRIBUTING.md

File metadata and controls

237 lines (174 loc) · 5.81 KB
Raw

Contributing Guidelines

Thank you for considering contributing to the MacUse Agent project!

Code of Conduct

Please maintain a friendly and inclusive communication approach. Be respectful of all contributors and users.

How to Contribute

Reporting Issues

  • Use issue templates to report bugs or request features
  • Search existing issues to avoid duplicates
  • Provide clear, detailed descriptions of the problem or feature request
  • Include environment information (OS version, Go version, etc.)

Submitting Code

  1. Fork this repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some AmazingFeature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Pull Request Guidelines

  • Write a clear PR title and description
  • Reference related issues using #issue-number
  • Include screenshots or examples for UI changes
  • Update documentation as needed

Development Guidelines

Environment Requirements

  • Go 1.24+
  • macOS (for RPA feature testing)
  • Optional: LM Studio for local LLM testing

Setting Up Development Environment

# Clone repository
git clone https://github.com/bzfq21/Go-ComputerUseAgent.git
cd Go-ComputeUseAgent

# Install dependencies
make deps

# Run tests
make test

# Build locally
make build

# Run with default config
./build/agent -help

Code Standards

  • Run make fmt to format code
  • Run make vet to check code
  • Run make lint for code quality checks

Project Structure

  • internal/core/llm/ - LLM client implementations
  • internal/core/rpa/ - RPA tools and automation
  • internal/core/workflow/ - Workflow engine
  • internal/config/ - Configuration management
  • internal/models/ - Data models

Testing

  • Run make test to execute all tests
  • Run make test-coverage to view test coverage
  • Run make test-race for race detection
  • Run make bench for benchmark tests

Adding New RPA Tools

To add a new RPA tool:

  1. Create a new file in internal/core/rpa/tools/ in the appropriate category (mouse, keyboard, screen, system)
  2. Implement the interfaces.Tool interface
  3. Register the tool in rpa.go in the registerAllTools() function
  4. Write tests for the new tool
  5. Update documentation

Example:

// internal/core/rpa/tools/mytool/mytool.go

package mytool

import (
    "github.com/bzfq21/Go-ComputerUseAgent/internal/core/rpa/interfaces"
)

type MyTool struct {
    // tool fields
}

func NewMyTool() interfaces.Tool {
    return &MyTool{}
}

func (t *MyTool) GetDefinition() (interfaces.ToolDefinition, error) {
    return interfaces.ToolDefinition{
        Name:        "my_tool",
        Category:    interfaces.CategoryCustom,
        Description: "Description of my tool",
        Parameters: map[string]interfaces.Parameter{
            "param1": {
                Type:        "string",
                Required:    true,
                Description: "Parameter description",
            },
        },
    }, nil
}

func (t *MyTool) Execute(ctx context.Context, params map[string]any) (*interfaces.ActionResult, error) {
    // implementation
    return &interfaces.ActionResult{
        Success: true,
        Data:    result,
    }, nil
}

Adding New LLM Providers

To add a new LLM provider:

  1. Create a new file in internal/core/llm/ implementing the LLMClient interface
  2. Add the provider to the client factory in factory.go
  3. Update configuration in config.go to support the new provider
  4. Write tests for the new client
  5. Update documentation

Commit Guidelines

Commit Message Format

Follow conventional commits format:

<type>(<scope>): <subject>

<body>

<footer>

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting, etc.)
  • refactor: Code refactoring
  • test: Adding or updating tests
  • chore: Maintenance tasks

Examples:

  • feat(llm): add support for new LLM provider
  • fix(rpa): resolve crash when taking screenshot
  • docs(readme): update installation instructions

Code Review Process

  1. Ensure all tests pass (make test)
  2. Ensure code is formatted (make fmt)
  3. Ensure vet passes (make vet)
  4. Run lint (make lint)
  5. Update documentation if needed
  6. Request review from maintainers

Pull Request Process

  1. Ensure PR description is clear and includes:
    • Summary of changes
    • Motivation for the change
    • Related issues
    • Testing performed
  2. Pass all CI checks
  3. Get approval from at least one maintainer
  4. Address review comments
  5. Merge into main branch
  6. Delete feature branch after merging

Release Process

Releases are managed by maintainers following semantic versioning:

  1. Update version in config.go default config
  2. Update CHANGELOG.md (if exists)
  3. Create git tag
  4. Build release binaries
  5. Create GitHub release

Coding Best Practices

  • Write clear, descriptive variable and function names
  • Add comments for complex logic
  • Handle errors appropriately
  • Write tests for new functionality
  • Keep functions focused and small
  • Follow Go best practices and idioms
  • Use interfaces for decoupling

Reporting Security Issues

For security vulnerabilities, please do not create a public issue. Instead:

  • Email the maintainers privately
  • Include detailed description of the vulnerability
  • Provide steps to reproduce
  • Wait for maintainers to respond and fix the issue

Resources

Getting Help

  • Check existing issues and discussions
  • Read source code comments
  • Ask questions in GitHub Discussions (if enabled)
  • Contact maintainers for guidance

Thank you for your contributions!