prefect-go/CONTRIBUTING.md

Contributing to prefect-go

Thank you for your interest in contributing to prefect-go!

Development Setup

Prerequisites

• Go 1.21 or later
• A running Prefect server (for integration tests)

Clone the Repository

git clone https://github.com/gregor/prefect-go.git
cd prefect-go

Install Dependencies

go mod download

Development Workflow

Running Tests

# Run unit tests
make test

# Run integration tests (requires running Prefect server)
make test-integration

# Generate coverage report
make test-coverage

Code Formatting

# Format code
make fmt

# Run linter
make lint

# Run go vet
make vet

Building Examples

make build-examples

Project Structure

prefect-go/
├── api/                    # OpenAPI specifications
├── cmd/                    # Command-line tools
│   └── generate/          # Code generator
├── examples/              # Example programs
│   ├── basic/            # Basic usage
│   ├── deployment/       # Deployment examples
│   ├── monitoring/       # Monitoring examples
│   └── pagination/       # Pagination examples
├── pkg/                   # Library code
│   ├── client/           # Main client and services
│   ├── errors/           # Error types
│   ├── models/           # Data models
│   ├── pagination/       # Pagination support
│   └── retry/            # Retry logic
└── tools/                 # Build tools

Code Style

• Follow standard Go conventions
• Use gofmt for formatting
• Write tests for new functionality
• Add GoDoc comments for exported types and functions
• Keep functions focused and small
• Use meaningful variable names

Commit Messages

• Use clear, descriptive commit messages
• Start with a verb in present tense (e.g., "Add", "Fix", "Update")
• Reference issue numbers when applicable

Example:

Add support for work pool queues

Implements work pool queue operations including create, get, and list.
Closes #123

Pull Request Process

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass (make test)
6. Run code formatting (make fmt)
7. Commit your changes with a clear message
8. Push to your fork (git push origin feature/amazing-feature)
9. Open a Pull Request

Pull Request Guidelines

• Provide a clear description of the changes
• Reference any related issues
• Ensure CI checks pass
• Request review from maintainers
• Be responsive to feedback

Adding New Features

Adding a New Service

1. Add the service struct in pkg/client/services.go or a new file
2. Add the service to the Client struct in pkg/client/client.go
3. Initialize the service in NewClient()
4. Implement service methods following existing patterns
5. Add tests for the new service
6. Update documentation

Example:

// NewService represents operations for new resources
type NewService struct {
    client *Client
}

func (s *NewService) Get(ctx context.Context, id uuid.UUID) (*models.NewResource, error) {
    var resource models.NewResource
    path := joinPath("/new_resources", id.String())
    if err := s.client.get(ctx, path, &resource); err != nil {
        return nil, fmt.Errorf("failed to get resource: %w", err)
    }
    return &resource, nil
}

Adding New Models

1. Add model structs in pkg/models/models.go
2. Follow existing naming conventions (Resource, ResourceCreate, ResourceUpdate)
3. Use proper JSON tags
4. Add documentation comments

Testing

Unit Tests

• Write unit tests for all new functions
• Use table-driven tests when appropriate
• Mock external dependencies
• Aim for >80% code coverage

Integration Tests

• Add integration tests for API operations
• Use the integration build tag
• Clean up resources after tests
• Handle test failures gracefully

Documentation

GoDoc

• Add package-level documentation
• Document all exported types and functions
• Include examples in documentation when helpful
• Use proper formatting (code blocks, links, etc.)

Examples

• Add examples for new features in examples/
• Make examples runnable and self-contained
• Include error handling
• Add comments explaining key concepts

Questions?

Feel free to open an issue if you have questions or need clarification.

License

By contributing, you agree that your contributions will be licensed under the MIT License.