# 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

```bash
# 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

```bash
# 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.

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

### Integration Tests

Integration tests that require Docker should be tagged:

```go
//go:build integration
// +build integration

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

Run integration tests:
```bash
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! 🚢