This file provides guidance to AI coding assistants when working with code in this repository.

• Database schema is defined in ./backend/migrator/migration/LATEST.sql
• Database migration files are in ./backend/migrator/<<version>>/
  • TestLatestVersion in ./backend/migrator/migrator_test.go needs update after new migration files are added
  • ./backend/migrator/migration/LATEST.sql should be updated for DDL migrations
• Files in ./backend/store are mappings to the database tables

ALWAYS follow these steps after making code changes:

1. Format — Run gofmt -w on modified files
2. Lint — Run golangci-lint run --allow-parallel-runners to catch issues
   • Important: Run golangci-lint repeatedly until there are no issues (the linter has a max-issues limit and may not show all issues in a single run)
3. Auto-fix — Use golangci-lint run --fix --allow-parallel-runners to fix issues automatically
4. Test — Run relevant tests before committing
5. Build — go build -ldflags "-w -s" -p=16 -o ./bytebase-build/bytebase ./backend/bin/server/main.go

1. Lint — Run pnpm --dir frontend lint --fix
2. Type check — Run pnpm --dir frontend type-check
3. Test — Run pnpm --dir frontend test

1. Format — Run buf format -w proto
2. Lint — Run buf lint proto
3. Generate — Run cd proto && buf generate

# Build
go build -ldflags "-w -s" -p=16 -o ./bytebase-build/bytebase ./backend/bin/server/main.go

# Start backend
PG_URL=postgresql://bbdev@localhost/bbdev go run ./backend/bin/server/main.go --port 8080 --data . --debug

# Run single test
go test -v -count=1 github.com/bytebase/bytebase/backend/path/to/tests -run ^TestFunctionName$

# Run multiple tests
go test -v -count=1 github.com/bytebase/bytebase/backend/path/to/tests -run ^(TestFunctionName|TestFunctionNameTwo)$

# Lint
golangci-lint run --allow-parallel-runners

# Install dependencies
pnpm --dir frontend i

# Dev server
pnpm --dir frontend dev

# Lint
pnpm --dir frontend lint

# Type check
pnpm --dir frontend type-check

# Test
pnpm --dir frontend test

# Format
buf format -w proto

# Lint
buf lint proto

# Generate
cd proto && buf generate

# Connect to Postgres
psql -U bbdev bbdev

• Follow Google style guides for all languages
  • Go
  • TypeScript and JavaScript
• Write clean, minimal code; fewer lines is better
• Prioritize simplicity for effective and maintainable software
• Only include comments that are essential to understanding functionality or convey non-obvious information

• Use standard Go error handling with detailed error messages
• Always use defer for resource cleanup like rows.Close() (sqlclosecheck)
• Avoid using defer inside loops (revive) — use IIFE or scope properly

• Follow AIPs
• When AIP and the proto guide conflict, AIP takes precedence
• Use HELLO for enum names, not TYPE_HELLO

• Follow TypeScript style with strict type checking
• i18n: All user-facing display text in the UI must be defined and maintained in ./frontend/src/locales/en-US.json using the i18n internationalization system. Do not hardcode any display strings directly in the source code

• Use American English
• Avoid plurals like "xxxList" for simplicity and to prevent singular/plural ambiguity stemming from poor design

• Follow conventional commit format

• Use organized imports (sorted by the import path)

• Use linting/formatting tools before committing

• Be explicit but concise about error cases

• Code Review — Follow Google's Code Review Guideline
• Author Responsibility — Authors are responsible for driving discussions, resolving comments, and promptly merging pull requests
• Breaking Changes — Add the breaking label to PRs that contain breaking changes, including:
  • API breaking changes (removed/renamed endpoints, changed request/response formats)
  • Database schema breaking changes that are not backward-compatible
  • Proto message breaking changes (removed/renamed fields, changed field types)
  • Configuration breaking changes (removed flags, changed behavior)
• Description — Clearly describe what the PR changes and why
• Testing — Include information about how the changes were tested

Always follow these guidelines to avoid common linting errors:

• Unused Parameters — Prefix unused parameters with underscore (e.g., func foo(_ *Bar))
• Modern Go Conventions — Use any instead of interface{} (since Go 1.18)
• Confusing Naming — Avoid similar names that differ only by capitalization
• Identical Branches — Don't use if-else branches that contain identical code
• Unused Functions — Mark unused functions with // nolint:unused comment if needed for future use
• Function Receivers — Don't create unnecessary function receivers; use regular functions if receiver is unused
• Proper Import Ordering — Maintain correct grouping and ordering of imports
• Consistency — Keep function signatures, naming, and patterns consistent with existing code
• Export Rules — Only export (capitalize) functions and types that need to be used outside the package
• Linting Command — Always run golangci-lint run --allow-parallel-runners without appending filenames to avoid "function not defined" errors (functions are defined in other files within the package)

• The database JSONB columns store JSON marshalled by protojson.Marshal in Go code. protojson.Marshal produces camelCased keys rather than the snake_case keys defined in the proto files. e.g. task_run becomes taskRun
• When modifying multiple files, run file modification tasks in parallel whenever possible, instead of processing them sequentially