# Contributing to BirdNET-Go

Thank you for your interest in contributing to BirdNET-Go!

## TL;DR - Quick Start

**Legal:** By contributing, you agree to the [CC BY-NC-SA 4.0 license](#license-and-legal), the [relicensing grant](#relicensing-grant) allowing a future move to an OSI-approved open source license, and [privacy-by-design principles](PRIVACY.md).

**Automated Setup (Linux/macOS):**

```bash
git clone https://github.com/tphakala/birdnet-go.git && cd birdnet-go
# install Task
sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b /usr/local/bin
# install development tools (compilers, linters, etc)
task setup-dev
# reload profile
source ~/.profile  # If Go was just installed
# start hot reloading dev server with
air realtime
```

**Dev Container (All Platforms):**

```bash
git clone https://github.com/tphakala/birdnet-go.git && cd birdnet-go
code .
# Press F1 → "Dev Containers: Reopen in Container"
air realtime
```

**Key Rules:**

- ❌ No API v1 expansion → use `internal/api/v2/`
- ❌ No telemetry without explicit user opt-in
- ❌ No `any` types in TypeScript
- ✅ Frontend embedded in Go binary (use `air`, not Vite dev server)
- ✅ Pre-commit hooks auto-format & lint
- ✅ AI-assisted coding encouraged - use responsibly

**Need details?** Read the sections below. **Questions?** [Discord](https://discord.gg/gcSCFGUtsd)

---

## Table of Contents

- [License and Legal](#license-and-legal)
- [Getting Started](#getting-started)
- [Development Setup](#development-setup)
- [Development Workflow](#development-workflow)
- [Code Quality](#code-quality)
- [Testing](#testing)
- [AI-Assisted Development](#ai-assisted-development)
- [Submitting Changes](#submitting-changes)
- [Additional Resources](#additional-resources)

## License and Legal

### Project License

By contributing to BirdNET-Go, you agree that your contributions will be licensed under **[CC BY-NC-SA 4.0](LICENSE)**:

- ✅ **Attribution** - Give appropriate credit
- ✅ **ShareAlike** - Same license for derivatives
- ❌ **NonCommercial** - No commercial use without permission
- ✅ **No Additional Restrictions** - Don't restrict others' rights

See [LICENSE](LICENSE) for full terms.

### Relicensing Grant

BirdNET-Go currently ships under CC BY-NC-SA 4.0, which is not an OSI-approved open source license. To keep the option of adopting a recognized open source license later, without having to track down every past contributor, contributions carry a forward relicensing grant.

By submitting a contribution (a pull request, patch, or any other change), you grant the project maintainer a perpetual, worldwide, non-exclusive, royalty-free, and irrevocable right to relicense your contribution, in whole or in part, under any license approved by the [Open Source Initiative](https://opensource.org/licenses) as an open source license. This grant is in addition to the CC BY-NC-SA 4.0 license above. It does not transfer your copyright, and you keep every right to your own work.

If you are unable or unwilling to grant this, please do not submit the contribution, or state your objection in the pull request so it can be handled separately.

### Privacy Policy

BirdNET-Go is **privacy-first** with zero data collection by default. Contributors must:

- Follow privacy-by-design principles
- Never add telemetry without explicit user opt-in
- Anonymize sensitive data (URLs, credentials, paths) in logs
- Document any external services in [PRIVACY.md](PRIVACY.md)

Read the full [Privacy Policy](PRIVACY.md) for details.

### Contributor Agreement

By submitting a pull request, you certify:

1. ✅ You have the right to submit under CC BY-NC-SA 4.0
2. ✅ Your contribution is original work or you have permission
3. ✅ You've read the [privacy policy](PRIVACY.md)
4. ✅ Your contribution follows privacy-by-design principles
5. ✅ You grant the relicensing rights described in [Relicensing Grant](#relicensing-grant)

## Getting Started

Before contributing:

1. **Read the [License](#license-and-legal)** and [Privacy Policy](PRIVACY.md)
2. **Review [ARCHITECTURE.md](ARCHITECTURE.md)** - Understand the tech stack
3. **Check [existing issues](https://github.com/tphakala/birdnet-go/issues)** - Avoid duplicates
4. **Join [Discord](https://discord.gg/gcSCFGUtsd)** - For discussions and support
5. **Read relevant CLAUDE.md files** - Development guidelines:
   - [CLAUDE.md](CLAUDE.md) - Project overview and universal rules
   - [internal/CLAUDE.md](internal/CLAUDE.md) - Go backend guidelines
   - [frontend/CLAUDE.md](frontend/CLAUDE.md) - Svelte 5 frontend guidelines
   - [internal/api/v2/CLAUDE.md](internal/api/v2/CLAUDE.md) - API v2 guidelines

   **Note:** CLAUDE.md files serve all contributors (AI-assisted or manual).

## Development Setup

**Requirements:**

- Go (version specified in `go.mod`)
- Node.js 22.x+ (LTS)
- Build tools (gcc, git, wget)
- TensorFlow Lite C library (auto-downloaded)

### Option 1: Automated Setup (Recommended)

**Linux (apt-based) or macOS (with Homebrew)**

**Step 1: Install Task Runner**

⚠️ **Security Note:** Review scripts before running: [Task install script](https://taskfile.dev/install.sh), [Homebrew install script](https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)

**Linux:**

```bash
sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b /usr/local/bin
```

**macOS:**

```bash
brew install go-task
```

**Alternative (if Go already installed):**

```bash
go install github.com/go-task/task/v3/cmd/task@latest
```

**Step 2: Clone and Setup**

```bash
git clone https://github.com/tphakala/birdnet-go.git
cd birdnet-go
task setup-dev
```

The `setup-dev` task installs:

- Go (version from `go.mod`), Node.js LTS, build tools
- golangci-lint, air, frontend dependencies
- Playwright browsers, git hooks (Husky)

**Note:** If Go is newly installed, run `source ~/.profile`

**Step 3: Start Developing**

```bash
air realtime      # Hot reload dev server (or: task dev_server)
```

### Option 2: Dev Container (VS Code)

**Prerequisites:** [Docker](https://docs.docker.com/get-docker/), [VS Code](https://code.visualstudio.com/), [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)

**Setup:**

1. Clone: `git clone https://github.com/tphakala/birdnet-go.git && cd birdnet-go`
2. Open: `code .`
3. Press `F1` → "Dev Containers: Reopen in Container"
4. Wait ~5-10 minutes for setup (frontend will be built automatically)
5. Start: `air realtime` or `task dev_server`

**Alternative Workflow (Active Frontend Development):**

For frontend-focused development with instant HMR:

```bash
# Terminal 1: Run Go server
air realtime

# Terminal 2: Run Vite dev server with HMR
cd frontend && npm run dev
```

Then open `http://localhost:5173/ui/` for instant hot module replacement.

**Note:** The devcontainer automatically builds the frontend during setup. If you need to rebuild manually, run `task frontend-build`.

**Features:**

- Pre-configured extensions (Go, Svelte, TypeScript, ESLint, Prettier, Playwright, TailwindCSS)
- Multiple shells (bash, zsh, fish, PowerShell)
- Port forwarding (8080)
- Auto-formatting on save

## Development Workflow

### Hot Reload with Air

[Air](https://github.com/air-verse/air) watches for changes and automatically rebuilds:

```bash
air realtime          # Realtime mode with hot reload
task dev_server       # Full development server
```

**What Air does:**

- Watches `.go` files for changes
- Recompiles Go binary with the previously built frontend
- Restarts server automatically

**Note:** Air does not build the frontend. Run `task frontend-build` first (already done by `task setup-dev`), or use `task frontend-watch` in a separate terminal for ongoing frontend changes.

### Frontend Development

The frontend can be developed in two modes:

**Option A: Embedded Mode (Recommended for backend changes)**

Use `air` or `task dev_server` - Go binary is recompiled with the previously built frontend on each change:

```bash
air realtime          # Hot reload for Go changes
task dev_server       # Full development server
```

**Option B: Vite HMR Mode (Recommended for frontend-only changes)**

Run Vite dev server alongside Go backend for instant HMR:

```bash
# Terminal 1: Start Go backend
air realtime

# Terminal 2: Start Vite dev server with HMR
cd frontend && npm run dev
```

Then open `http://localhost:5173/ui/` for HMR. Vite proxies `/api` requests to the Go backend.

**Use Vite HMR for:**

- Rapid UI prototyping with instant updates
- Component styling and layout changes
- Testing components in isolation
- Running frontend tests

### Building

```bash
task                  # Default build (auto-detect platform)
task linux_amd64      # Cross-platform builds
task linux_arm64
task darwin_amd64
task darwin_arm64
task windows_amd64
task clean            # Clean artifacts
```

## Code Quality

**All code must pass linting before commit.** Pre-commit hooks run automatically.

### Go Linting

Configuration: [.golangci.yaml](.golangci.yaml)

```bash
golangci-lint run -v                    # All files
golangci-lint run -v internal/api/v2/   # Specific path
golangci-lint run --fix                 # Auto-fix
```

### Frontend Linting

Configuration: `frontend/eslint.config.js`, `frontend/.prettierrc`, `frontend/.stylelintrc.json`, `frontend/tsconfig.json`

```bash
task frontend-quality       # Comprehensive check (recommended)
task frontend-lint          # ESLint + Prettier + Stylelint
task frontend-typecheck     # TypeScript checking
npm run ast:all             # AST-grep security/pattern checks
task frontend-lint-fix      # Auto-fix issues
```

### Pre-commit Hooks

Configured automatically via [Husky](https://typicode.github.io/husky/) during `task setup-dev`:

**Go files:**

- Auto-format with `gofmt`
- Lint with `golangci-lint`
- Block commit if errors

**Frontend files:**

- Format with Prettier
- Lint with ESLint + Stylelint
- Type check TypeScript
- Block commit if errors

**Manual initialization (if needed):**

```bash
cd frontend && npm run prepare
ls -la ../.git/hooks/pre-commit  # Verify installation
```

**Troubleshooting:**

```bash
cd frontend && npm run prepare           # Reinitialize
which golangci-lint                      # Check PATH
echo $PATH                               # Verify $HOME/go/bin
```

**Bypassing (strongly discouraged):**

```bash
git commit --no-verify -m "message"
```

⚠️ Bypassed commits may be rejected during code review.

### AST-Grep Analysis

```bash
cd frontend
npm run ast:all              # All checks
npm run ast:security         # Security scanning
npm run ast:svelte5          # Svelte 5 best practices
npm run ast:fix              # Auto-fix
```

See [frontend/doc/AST-GREP-SETUP.md](frontend/doc/AST-GREP-SETUP.md) for details.

## Testing

### Go Tests

```bash
task test                    # All tests
task test-verbose            # Verbose output
task test-coverage           # With coverage
go test -race -v ./...       # Race detector
go test -v ./internal/api/v2/...  # Specific package
```

### Frontend Tests

```bash
task frontend-test              # Unit tests
task frontend-test-coverage     # With coverage
task e2e-test                   # Playwright E2E
task e2e-test-headed            # Headed mode (debug)
task e2e-test-ui                # UI mode
task e2e-report                 # View report
```

## AI-Assisted Development

BirdNET-Go **welcomes AI-assisted coding tools**. The main developer uses [Claude Code](https://claude.ai/claude-code), and all PRs receive [CodeRabbit AI](https://coderabbit.ai/) reviews.

### CLAUDE.md Guidelines

Project guidelines are in CLAUDE.md files (see [Getting Started](#getting-started)). These files work for both AI assistants and manual development.

### Responsible AI Usage

**✅ Good Use:**

- Understand codebase patterns
- Generate boilerplate and tests
- Refactor while maintaining behavior
- Write documentation
- Identify bugs and edge cases

**⚠️ Requirements:**

- Review all AI-generated code
- Understand what code does
- Test thoroughly
- Follow project guidelines
- Respect privacy (no sensitive data sharing)

**❌ Prohibited:**

- Submitting code without understanding
- Bypassing quality checks
- Sharing proprietary/sensitive data
- Unverified licensing/attribution
- Misleading/obfuscated code

### Getting Started with Claude Code

1. Install: [Claude Code guide](https://docs.claude.com/en/docs/claude-code)
2. Open BirdNET-Go repository
3. CLAUDE.md files provide automatic context
4. Ask Claude for help with specific tasks

### Quality Gate (Mandatory for AI-Assisted PRs)

If you're using an AI coding tool to generate your PR, you **must** run the preflight quality gate before pushing. Manual contributors are encouraged to review the checklist too. The gate is defined in `.agents/skills/preflight/SKILL.md` and catches the issues that reviewers would otherwise flag.

- **Claude Code**: Run `/preflight` before pushing
- **Codex, Gemini CLI, Windsurf**: The skill auto-discovers from `.agents/skills/`
- **Cursor, Copilot**: `AGENTS.md` instructs your tool to run the gate
- **Manual check**: Read `.agents/skills/preflight/SKILL.md` and follow its process

Each PR must contain **exactly one feature, one fix, or one refactor**. PRs that batch multiple concerns will not be merged. If your task spans multiple changes, split them into separate branches and PRs.

PRs that skip preflight typically require 5-10 review rounds. Running preflight locally takes minutes and usually results in a clean first review.

**Questions?** Join [Discord](https://discord.gg/gcSCFGUtsd) to discuss AI-assisted development.

## Submitting Changes

### Branch Naming

```bash
git checkout -b feature/short-description   # Features
git checkout -b fix/issue-number-desc       # Bug fixes
git checkout -b docs/what-updated           # Documentation
```

### Before Committing

```bash
git pull origin main                        # Update from main
git checkout -b feature/my-feature          # Create branch
golangci-lint run -v                        # Lint Go
task frontend-quality                       # Lint frontend
task test                                   # Test Go
task frontend-test                          # Test frontend
```

### Commit Messages

Follow [Conventional Commits](https://www.conventionalcommits.org/):

```text
type(scope): brief description

Longer explanation if needed.

Fixes #123
```

**Types:** `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `perf`

**Examples:**

```text
feat(api): add spectrogram generation endpoint
fix(frontend): resolve audio player freeze (BG-14)
docs(contributing): streamline documentation
refactor(analysis): optimize detection pipeline
```

### Pull Request Process

**PR Title:** `type(scope): Brief description`

**PR Template:**

```markdown
## Summary

Brief description of changes.

## Changes

- Change 1
- Change 2

## Testing

- [ ] Go tests pass (`task test`)
- [ ] Frontend tests pass (`task frontend-test`)
- [ ] Linting passes
- [ ] Manual testing completed
- [ ] Preflight quality gate passed (AI-assisted PRs)

## Related Issues

Fixes #123
```

**Review Process:**

- CodeRabbit AI automatically reviews
- Address feedback promptly
- Keep discussions constructive
- Squash commits if requested

### Critical Constraints

- **NEVER expand API v1** - Use `internal/api/v2/`
- **Always lint before commit** - `golangci-lint run -v` and `task frontend-quality`
- **Branch from updated main** - `git pull origin main` first
- **No `any` types in TypeScript** - Properly type all parameters

## Additional Resources

### Documentation

- [User Guide](doc/wiki/guide.md)
- [Installation Guide](doc/wiki/installation.md)
- [Security Guide](doc/wiki/security.md)
- [Hardware Recommendations](doc/wiki/hardware.md)
- [AST-Grep Setup](frontend/doc/AST-GREP-SETUP.md)

### Development Guidelines

- [Architecture](ARCHITECTURE.md)
- [Go Backend Guidelines](internal/CLAUDE.md)
- [Frontend Guidelines](frontend/CLAUDE.md)
- [API v2 Guidelines](internal/api/v2/CLAUDE.md)

### Community

- [GitHub Repository](https://github.com/tphakala/birdnet-go)
- [Discord Community](https://discord.gg/gcSCFGUtsd)
- [Issue Tracker](https://github.com/tphakala/birdnet-go/issues)
- [BirdNET Upstream](https://github.com/birdnet-team/BirdNET-Analyzer)

### Quick Command Reference

```bash
# Setup
task setup-dev          # Setup environment
task --list             # List all tasks

# Development
air realtime            # Hot reload
task dev_server         # Full dev server

# Quality
golangci-lint run -v    # Go linting
task frontend-quality   # Frontend quality

# Testing
task test               # Go tests
task frontend-test      # Frontend tests
task e2e-test           # E2E tests

# Building
task                    # Default build
task clean              # Clean artifacts
```

---

**Thank you for contributing to BirdNET-Go!** 🎉

**Questions?** [Discord](https://discord.gg/gcSCFGUtsd) | [Discussions](https://github.com/tphakala/birdnet-go/discussions) | [Issues](https://github.com/tphakala/birdnet-go/issues)