Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
569 lines (391 loc) · 16.8 KB

CONTRIBUTING.md

File metadata and controls

569 lines (391 loc) · 16.8 KB
Raw

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, the relicensing grant allowing a future move to an OSI-approved open source license, and privacy-by-design principles.

Automated Setup (Linux/macOS):

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):

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

Table of Contents

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:

  • ✅ 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 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 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

Read the full Privacy Policy 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
  4. ✅ Your contribution follows privacy-by-design principles
  5. ✅ You grant the relicensing rights described in Relicensing Grant

Getting Started

Before contributing:

  1. Read the License and Privacy Policy

  2. Review ARCHITECTURE.md - Understand the tech stack

  3. Check existing issues - Avoid duplicates

  4. Join Discord - For discussions and support

  5. Read relevant CLAUDE.md files - Development 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, Homebrew install script

Linux:

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

macOS:

brew install go-task

Alternative (if Go already installed):

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

Step 2: Clone and Setup

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

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

Option 2: Dev Container (VS Code)

Prerequisites: Docker, VS Code, Dev Containers extension

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:

# 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 watches for changes and automatically rebuilds:

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:

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:

# 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

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-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

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 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):

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

Troubleshooting:

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

Bypassing (strongly discouraged):

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

⚠️ Bypassed commits may be rejected during code review.

AST-Grep Analysis

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 for details.

Testing

Go Tests

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

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, and all PRs receive CodeRabbit AI reviews.

CLAUDE.md Guidelines

Project guidelines are in CLAUDE.md files (see 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
  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 to discuss AI-assisted development.

Submitting Changes

Branch Naming

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

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:

type(scope): brief description

Longer explanation if needed.

Fixes #123

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

Examples:

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:

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

Development Guidelines

Community

Quick Command Reference

# 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 | Discussions | Issues