1# Contributing to Matcha
  2
  3Thank you for your interest in contributing to Matcha! This guide will help you get started.
  4
  5## Getting Started
  6
  7### Prerequisites
  8
  9- [Go 1.26+](https://go.dev/dl/)
 10- A terminal emulator with modern capabilities (kitty, ghostty, alacritty, etc.)
 11- An IMAP email account for testing
 12
 13### Setup
 14
 15```bash
 16git clone https://github.com/floatpane/matcha.git
 17cd matcha
 18go mod tidy
 19```
 20
 21### Build & Run
 22
 23```bash
 24make build     # builds to bin/matcha
 25make run       # builds and runs in one step
 26```
 27
 28### Testing
 29
 30```bash
 31make test              # run all tests
 32make test-verbose      # run tests with verbose output
 33make test-coverage     # run tests and generate a coverage report
 34```
 35
 36### Linting
 37
 38```bash
 39make lint       # runs go fmt and go vet
 40```
 41
 42## Making Changes
 43
 44### Branch Naming
 45
 46Create a branch from `master` using one of these prefixes:
 47
 48- `feature/` — new functionality
 49- `fix/` — bug fixes
 50- `docs/` — documentation changes
 51- `refactor/` — code restructuring without behavior changes
 52
 53### Commit Messages
 54
 55We use [Conventional Commits](https://www.conventionalcommits.org/). Format your commit messages as:
 56
 57```
 58type(scope): short description
 59```
 60
 61Common types: `feat`, `fix`, `docs`, `test`, `ci`, `chore`.
 62
 63Keep commit messages to 40 characters or fewer.
 64
 65Examples:
 66```
 67feat(compose): add CC/BCC field support
 68fix(imap): handle connection timeout gracefully
 69docs: update installation instructions
 70```
 71
 72### Before Submitting a PR
 73
 741. Run `make lint` and fix any issues.
 752. Run `make test` and make sure all tests pass.
 763. Keep your PR focused — one logical change per PR.
 774. Write a clear PR description explaining **what** changed and **why**.
 78
 79## Reporting Bugs
 80
 81Open an issue using the [bug report template](https://github.com/floatpane/matcha/issues/new?template=bug_report.md). Include:
 82
 83- Steps to reproduce the issue
 84- Expected vs. actual behavior
 85- Your OS, terminal emulator, and Matcha version (`matcha --version`)
 86
 87## Requesting Features
 88
 89Open an issue using the [feature request template](https://github.com/floatpane/matcha/issues/new?template=feature_request.md) with a clear description of the problem you're trying to solve and your proposed solution.
 90
 91## AI Policy
 92
 93We welcome contributions that use AI-assisted tools (Copilot, Claude, ChatGPT, etc.) as part of the development process. That said, contributors are fully responsible for any code they submit, regardless of how it was written.
 94
 95**What we expect:**
 96
 97- **Understand what you submit.** You should be able to explain every line of your PR. If you can't explain it, don't submit it.
 98- **Review AI output carefully.** AI tools can produce plausible-looking code that is subtly wrong, insecure, or doesn't match the project's patterns. Treat AI suggestions the same way you'd treat a Stack Overflow snippet — verify before committing.
 99- **Don't submit AI-generated issues, reviews, or comments.** Discussions should be genuine human communication. Using AI to help draft something is fine, but don't paste raw AI output into issues or review comments.
100- **No AI-generated tests that don't actually test anything.** Tests must be meaningful and actually validate behavior, not just exist for coverage numbers.
101- **Attribute when appropriate.** If a significant portion of your contribution was AI-assisted, a brief mention in your PR description is appreciated but not required.
102
103**What we won't accept:**
104
105- Bulk PRs of AI-generated refactors, documentation, or "improvements" that weren't requested.
106- Code that introduces hallucinated dependencies, APIs, or patterns that don't exist in the project.
107- Contributions where the author clearly doesn't understand the changes they're proposing.
108
109The goal is simple: AI is a tool. Use it well, take ownership of the output, and make sure your contribution actually improves the project.
110
111## Code of Conduct
112
113This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). By participating, you agree to uphold a welcoming and respectful environment for everyone.