Contributing to Go Overlay¶

Thank you for your interest in contributing to Go Overlay! This guide will help you get started with contributing to the project.

Getting Started¶

Before you begin:

• Make sure you have Go installed (version 1.21 or later)
• Familiarize yourself with the project by reading the documentation
• Check the roadmap to see what features are planned
• Look at existing issues and pull requests to avoid duplicate work

Fork and Pull Request Workflow¶

1. Fork the Repository¶

1. Navigate to the Go Overlay repository
2. Click the "Fork" button in the top right corner
3. Clone your fork locally:

git clone https://github.com/YOUR-USERNAME/go-entrypoint.git
cd go-entrypoint

2. Create a Branch¶

Create a new branch for your feature or bug fix:

git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix

Use descriptive branch names: - feature/ for new features - fix/ for bug fixes - docs/ for documentation changes - refactor/ for code refactoring

3. Make Your Changes¶

Make your changes following the code style guidelines below. Ensure your code:

• Follows Go best practices
• Includes appropriate comments
• Handles errors properly
• Is well-tested

4. Commit Your Changes¶

Write clear, descriptive commit messages:

git add .
git commit -m "Add feature: brief description of what you added"

Good commit message examples: - Add support for environment variable substitution in config - Fix race condition in service state management - Refactor timeout handling for better clarity - Update documentation for dependency management

5. Push and Create Pull Request¶

Push your changes to your fork:

git push origin feature/your-feature-name

Then:

1. Go to your fork on GitHub
2. Click "Compare & pull request"
3. Fill in the PR template with:
4. Description of changes
5. Related issue numbers (if applicable)
6. Testing performed
7. Screenshots (if UI changes)
8. Submit the pull request

6. Code Review Process¶

• Maintainers will review your PR
• Address any feedback or requested changes
• Once approved, your PR will be merged

Code Style Guidelines¶

Go Code Style¶

Follow standard Go conventions:

• Use gofmt to format your code
• Follow Effective Go guidelines
• Use meaningful variable and function names
• Keep functions focused and concise

// Good: Clear, descriptive names
func StartServiceWithTimeout(service *Service, timeout time.Duration) error {
    // Implementation
}

// Bad: Unclear abbreviations
func StSvcWT(s *Service, t time.Duration) error {
    // Implementation
}

Error Handling¶

Always handle errors explicitly:

// Good
result, err := someOperation()
if err != nil {
    return fmt.Errorf("failed to perform operation: %w", err)
}

// Bad
result, _ := someOperation()

Comments¶

• Add comments for exported functions and types
• Use godoc-style comments
• Explain complex logic

// StartService initializes and starts the specified service.
// It returns an error if the service fails to start within the configured timeout.
func StartService(service *Service) error {
    // Implementation
}

Package Organization¶

• Keep related functionality together
• Use internal packages for implementation details
• Export only what's necessary

Testing Requirements¶

All contributions must include appropriate tests.

Writing Tests¶

• Place tests in *_test.go files
• Use table-driven tests for multiple scenarios
• Test both success and error cases
• Aim for good code coverage

Example test structure:

func TestServiceStart(t *testing.T) {
    tests := []struct {
        name    string
        service *Service
        wantErr bool
    }{
        {
            name:    "successful start",
            service: &Service{Name: "test", Command: "echo"},
            wantErr: false,
        },
        {
            name:    "invalid command",
            service: &Service{Name: "test", Command: ""},
            wantErr: true,
        },
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            err := tt.service.Start()
            if (err != nil) != tt.wantErr {
                t.Errorf("Start() error = %v, wantErr %v", err, tt.wantErr)
            }
        })
    }
}

Running Tests¶

Run all tests before submitting:

# Run all tests
make test

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

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

Test Coverage¶

• Aim for at least 70% code coverage
• Focus on testing critical paths
• Include edge cases and error conditions

Documentation¶

If your changes affect user-facing functionality:

• Update relevant documentation in the docs/ directory
• Add examples if introducing new features
• Update the README if necessary
• Keep documentation clear and concise

Reporting Issues¶

When reporting bugs or requesting features:

1. Check if the issue already exists
2. Use the issue template
3. Provide clear reproduction steps
4. Include relevant logs and configuration
5. Specify your environment (OS, Go version, etc.)

Code of Conduct¶

• Be respectful and inclusive
• Welcome newcomers
• Focus on constructive feedback
• Help maintain a positive community

Questions?¶

If you have questions:

• Open a discussion on GitHub
• Check existing documentation
• Review closed issues for similar questions

Thank you for contributing to Go Overlay! 🎉