diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..43ff8cc --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,224 @@ +# Contributing to Local Docker Proxy + +Thank you for your interest in contributing! This guide covers how to report issues, submit pull requests, and develop locally. + +## Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [Reporting Bugs](#reporting-bugs) +- [Suggesting Enhancements](#suggesting-enhancements) +- [Development Setup](#development-setup) +- [Code Style Guidelines](#code-style-guidelines) +- [Testing](#testing) +- [Commit Message Guidelines](#commit-message-guidelines) +- [Pull Request Process](#pull-request-process) +- [License](#license) + +## Code of Conduct + +Be respectful, accept constructive criticism gracefully, and focus on what's best for the community. Harassment, trolling, and personal attacks are not tolerated. + +## Reporting Bugs + +**Before submitting:** +- Search existing issues to avoid duplicates +- Verify the bug on the latest version +- Test on a clean environment + +**Include in your report:** +- OS type, version, and architecture (AMD64/ARM64) +- Docker and Docker Compose versions +- Steps to reproduce (numbered and clear) +- Expected vs. actual behavior +- Error messages (full text, not screenshots) +- Relevant `.env` and `docker-compose.yml` sections (redact passwords) + +**Good title:** `setup.sh fails on Fedora 39 ARM64 - mkcert download error` + +## Suggesting Enhancements + +When proposing a feature: +1. Check if it's already proposed in existing issues +2. Explain the use case and why it's needed +3. Describe your proposed solution +4. Note any breaking changes + +## Development Setup + +**Prerequisites:** +- Git +- Docker Engine 20.10.0+ +- Docker Compose v2.0.0+ +- bats-core for testing + +**Setup steps:** + +```bash +# 1. Clone your fork +git clone https://github.com/YOUR-USERNAME/docker-proxy.git +cd docker-proxy + +# 2. Install test dependencies +# macOS: brew install bats-core +# Ubuntu/Debian: sudo apt install bats +# Fedora/RHEL: sudo dnf install bats +# Arch Linux: sudo pacman -S bats + +# 3. Run the proxy +./setup.sh + +# 4. Verify +docker ps | grep traefik +``` + +## Code Style Guidelines + +### Shell Scripts + +- Use `#!/bin/bash` and `set -e` +- Quote variables: `"$VARIABLE"` +- Use lowercase for local vars, UPPERCASE for env vars +- Use logging functions: `log_info()`, `log_error()`, `log_warn()`, `log_success()` +- Handle multiple platforms with case statements + +**Example:** +```bash +detect_os() { + case "$(uname -m)" in + x86_64) ARCH="amd64" ;; + aarch64|arm64) ARCH="arm64" ;; + *) log_error "Unsupported architecture"; exit 1 ;; + esac +} +``` + +### YAML Files + +- Use 2 spaces for indentation (no tabs) +- Order keys logically: image, container_name, restart, networks, ports, volumes, labels +- Add comments for complex configurations +- Use YAML anchors for repeated configs + +### Markdown Documentation + +- Use clear headings (# H1, ## H2, ### H3) +- Always specify language for code blocks +- Use relative paths for internal links +- Use emoji indicators: ✅ ❌ 📖 ⚠️ + +## Testing + +**Run tests:** +```bash +# All tests +bats tests/ + +# Specific file +bats tests/setup.bats + +# Verbose output +bats --verbose-run tests/ +``` + +**Writing tests:** +- Use bats-core framework +- Test all code paths for new functions +- Include error handling tests +- Add platform-specific tests when needed +- See `tests/setup.bats` for examples + +**Coverage requirements:** +- New shell functions: 100% of code paths +- New features: At least one integration test +- Bug fixes: At least one regression test + +**CI runs tests on:** +- ubuntu-latest +- macos-latest + +## Commit Message Guidelines + +**Format:** +``` +(): + + + +