Contributing to floop

February 28, 2026 · View on GitHub

Thank you for your interest in contributing to floop! This guide will help you get started.

Prerequisites

Development Setup

# Clone the repository
git clone https://github.com/nvandessel/floop.git
cd floop

# Build
make build

# Run tests
make test

# Run the full CI suite (format check + lint + vet + test + build)
make ci

Workflow

  1. Find or create an issue — Check existing issues or open a new one describing the change
  2. Fork and branch — Create a feature branch from main (feat/description or fix/description)
  3. Write code — Follow the Go coding standards
  4. Write tests — All changes need tests (see Testing below)
  5. Update docs — If adding or changing CLI commands or flags, update docs/CLI_REFERENCE.md
  6. Run CI locally — make ci must pass
  7. Submit a PR — Reference the related issue

Code Standards

See docs/GO_GUIDELINES.md for the full guide. Key points:

  • Run go fmt ./... before committing
  • Use fmt.Errorf("context: %w", err) for error wrapping
  • Keep interfaces small (1-3 methods)
  • Pass context.Context as the first parameter

Testing

  • Table-driven tests with t.Run() for all functions with multiple input cases
  • Test both success and error paths
  • Use go test -race ./... to catch race conditions
make test              # Run all tests
make test-coverage     # Generate coverage report

Commit Messages

Use conventional commits:

  • feat: new features
  • fix: bug fixes
  • docs: documentation changes
  • test: test additions or changes
  • chore: maintenance

Release Process

Releases are automated using GoReleaser and GitHub Actions.

  • Patches auto-release when code changes merge to main
  • Skip auto-release with [skip release] in the commit message or a skip-release label on the PR
  • Minor/major releases are manual: gh workflow run version-bump.yml -f bump=<minor|major>

For detailed instructions, see docs/RELEASE_PROCESS.md.

Pull Request Expectations

  • PRs should be focused — one logical change per PR
  • Include a description of what changed and why
  • Reference the related issue (Fixes #123 or Closes #123)
  • All CI checks must pass
  • Maintain or improve test coverage

Reporting Issues

License

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