buque/CONTRIBUTING.md

Contributing to Buque

Thank you for your interest in contributing to Buque! This document provides guidelines and instructions for contributing.

Code of Conduct

This project adheres to a code of conduct. By participating, you are expected to uphold this code. Please be respectful and constructive in all interactions.

How to Contribute

Reporting Bugs

Before creating bug reports, please check existing issues to avoid duplicates. When creating a bug report, include:

• Clear title and description
• Steps to reproduce the issue
• Expected behavior
• Actual behavior
• Environment details (OS, Docker version, Go version)
• Log output if applicable

Suggesting Enhancements

Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion, include:

• Clear title and description
• Use case for the enhancement
• Proposed solution or implementation ideas
• Alternatives considered

Pull Requests

1. Fork the repository and create your branch from main
2. Make your changes following the coding standards
3. Add tests if applicable
4. Update documentation if needed
5. Ensure tests pass (make test)
6. Format your code (make fmt)
7. Run linter (make vet)
8. Commit your changes with clear commit messages
9. Push to your fork and submit a pull request

Pull Request Guidelines

• Use descriptive titles and descriptions
• Reference related issues
• Keep changes focused and atomic
• Add tests for new functionality
• Update README.md if needed
• Follow the existing code style

Development Setup

Prerequisites

• Go 1.21 or higher
• Docker 20.10 or higher
• Make

Setting Up Development Environment

# Clone your fork
git clone https://github.com/yourusername/buque.git
cd buque

# Install dependencies
make deps

# Build the project
make build

# Run tests
make test

Running Tests

# Run all tests
make test

# Run specific tests
go test ./internal/docker/...

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

Code Style

• Follow standard Go conventions and idioms
• Use gofmt for formatting
• Write clear, self-documenting code
• Add comments for complex logic
• Keep functions small and focused

Commit Messages

Follow conventional commit 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

Example:

feat(proxy): add support for custom SSL certificates

Add ability to specify custom SSL certificates for nginx-proxy
instead of relying only on Let's Encrypt.

Closes #123

Project Structure

buque/
├── cmd/buque/           # Main application entry point
├── internal/
│   ├── cmd/             # CLI command implementations
│   ├── config/          # Configuration management
│   ├── docker/          # Docker operations
│   ├── models/          # Data models
│   ├── proxy/           # Nginx-proxy management
│   └── stats/           # Statistics collection
├── examples/            # Example configurations
├── Makefile            # Build automation
├── go.mod              # Go dependencies
└── README.md           # Project documentation

Testing

Unit Tests

Place unit tests in _test.go files alongside the code they test.

func TestFunction(t *testing.T) {
    // Test implementation
}

Integration Tests

Integration tests that require Docker should be tagged:

//go:build integration
// +build integration

func TestDockerIntegration(t *testing.T) {
    // Test implementation
}

Run integration tests:

go test -tags=integration ./...

Documentation

• Update README.md for user-facing changes
• Update code comments for API changes
• Add examples for new features
• Keep documentation clear and concise

Release Process

Releases are managed by maintainers:

1. Update version in code
2. Update CHANGELOG.md
3. Create and push git tag
4. Build and upload binaries
5. Create GitHub release

Questions?

Feel free to open an issue for questions or reach out to maintainers.

Thank you for contributing to Buque! 🚢