go-client/CONTRIBUTING.md

Contributing to TorrentClaw Go Client

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

Getting Started

1. Fork the repository on GitHub
2. Clone your fork locally:

   git clone https://github.com/YOUR-USERNAME/torrentclaw-go-client.git
   cd torrentclaw-go-client
   

3. Create a branch for your change:

   git checkout -b feature/my-feature
   

4. Make your changes, write tests, and ensure everything passes
5. Commit with a clear message (see Commit Messages)
6. Push to your fork and open a Pull Request

Development Setup

You need Go 1.22+ installed.

Git Hooks (Lefthook)

This project uses Lefthook to run pre-commit checks and validate commit messages automatically.

# Install lefthook (pick one):
brew install lefthook          # macOS
go install github.com/evilmartians/lefthook@latest  # Go
npm install -g lefthook        # npm

# Activate hooks in your local clone:
make install-hooks
# or: lefthook install

Once installed, every commit will automatically:

• pre-commit: check gofmt, run go vet, and run golangci-lint (if installed)
• commit-msg: validate the message follows Conventional Commits

Make Targets

make test       # Run tests
make coverage   # Run tests with coverage (90% threshold enforced)
make lint       # Run golangci-lint
make fmt        # Format code (gofmt -s -w)
make check      # Verify formatting (no write, CI-friendly)
make vet        # Run go vet
make all        # fmt + vet + lint + test
make install-hooks  # Install lefthook git hooks

Code Style

• Run gofmt on all code (or make fmt)
• Run golangci-lint (or make lint)
• This project has zero external dependencies — keep it that way. Only use the Go standard library.
• Follow existing patterns in the codebase:
  • Functional options for configuration (WithXxx)
  • context.Context as the first parameter on all public methods
  • Custom error types with helper methods

Running Tests

# All tests
make test

# Specific test
go test -run TestSearch -v ./...

# With coverage report
make coverage

Tests run in CI against Go 1.22, 1.23, and 1.24. A minimum of 90% code coverage is enforced.

Commit Messages

This project enforces Conventional Commits via a git hook. Format:

<type>[optional scope]: <description>

Allowed types: feat, fix, docs, test, chore, refactor, ci, style, perf, build

Examples:

feat: add support for filtering by audio codec
fix(client): handle nil response body on 204
docs: update Quick Start example
test: add edge case tests for retry logic
chore: update CI matrix to Go 1.24
refactor: extract retry logic into helper

Pull Request Guidelines

• Keep PRs focused — one feature or fix per PR
• Include tests for new functionality
• Update documentation if the public API changes
• Ensure all CI checks pass before requesting review
• Link related issues in the PR description

Reporting Bugs

Open an issue with:

• Description — what went wrong
• Steps to reproduce — minimal code or commands to trigger the bug
• Expected behavior — what you expected to happen
• Actual behavior — what actually happened
• Environment — Go version, OS, client version

Requesting Features

Open an issue with:

• Problem — what are you trying to solve?
• Proposed solution — how do you think it should work?
• Alternatives considered — other approaches you thought about

Code of Conduct

This project follows the Contributor Covenant v2.1.

In short:

• Be respectful — treat everyone with dignity regardless of background or experience level
• Be constructive — focus on what's best for the project and community
• Be collaborative — welcome newcomers, help others learn
• No harassment — unacceptable behavior includes trolling, insults, and unwelcome attention

Violations can be reported to the project maintainers. All complaints will be reviewed and investigated promptly and fairly.

Questions?

If you're unsure about something, open a discussion or reach out on Discord (coming soon).

---

Thank you for helping make TorrentClaw better!