Skip to main content

​
Git workflow

1

Create a feature branch from main

git checkout -b feat/your-feature-name
Use a prefix that matches your change type: feat/, fix/, docs/, refactor/.
2

Make focused changes

Keep commits small and atomic. Each commit should represent a single logical change that can be understood and reverted independently.
3

Write or update tests

# Frontend tests
cd frontend && npm test

# Rust tests
cd backend && cargo test
4

Open a pull request

Include in your PR description:
  • What: Brief description of changes
  • Why: Motivation or issue reference
  • How: Implementation approach (if non-obvious)
  • Testing: How you tested the changes
5

Address review feedback

Respond to review comments and push additional commits to address feedback. Request re-review when ready.
6

Merge after approval

PRs are merged after at least one approving review and all CI checks passing.

​
Commit convention

All commits must follow Conventional Commits. PRs with non-conforming messages will be asked to rebase. 
type(scope): description
Examples: 
feat(frontend): add dark mode toggle
fix(backend): resolve clipboard race condition
docs(readme): update installation instructions
refactor(hooks): extract audio logic to separate hook
test(services): add groq service unit tests
TypeWhen to use
featNew feature
fixBug fix
docsDocumentation only
refactorCode change that neither fixes a bug nor adds a feature
testAdding or updating tests
choreBuild process, tooling, or dependency updates

​
Code of conduct

This project follows the guidelines in CODE_OF_CONDUCT.md. All contributors are expected to uphold a respectful and inclusive environment.

​
Reporting bugs

Open an issue on GitHub Issues and include:
  1. Trueears version (found in Settings > About)
  2. Operating system and version
  3. Steps to reproduce the issue
  4. Expected vs actual behavior
  5. Console errors (open with F12 in dev mode)
  6. Screenshots if relevant

​
Performance budgets

Keep these targets in mind when contributing:
MetricTarget
Cold start to ready< 2 seconds
Hotkey to recording< 100ms
Transcription display< 3 seconds
Idle memory< 50MB
Recording memory< 150MB
Bundle size< 25MB
PRs that regress any of these budgets must include justification and benchmarks.

​
Security guidelines

  • API keys: Store in Tauri Store (@tauri-apps/plugin-store), never in localStorage
  • Audio buffers: Clear after transcription completes
  • Clipboard: Read only on user action, write only final output
  • LLM prompts: Include injection-prevention instructions
  • User input: Validate at all trust boundaries

​
Coding standards

All contributions must pass linting and formatting checks before merge. 
npx eslint .

​
License

By contributing, you agree that your contributions will be licensed under AGPL-3.0.