Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
206 lines (157 loc) · 7.76 KB

CONTRIBUTING.md

File metadata and controls

206 lines (157 loc) · 7.76 KB
Raw

Contributing to git-courer

Thanks for your interest! We're glad you're here.

Please note that this project is governed by a Code of Conduct. By participating, you agree to uphold its terms.

Table of Contents

What we're working on

Check GitHub Issues for open tasks. We're actively working on:

  • Improving prompt quality across different model sizes
  • Expanding MCP tool coverage
  • Better handling of edge cases (empty repos, large diffs, merge conflicts)

Good first issues

If you're new to the project, look for issues labeled good first issue. These are smaller, well-scoped tasks that don't require deep knowledge of the codebase.

Setup

Requirements: Go 1.26+ · Git · Ollama (optional, for integration tests)

git clone https://github.com/blak0p/git-courer.git
cd git-courer
go build -o git-courer ./cmd/main.go

Quick sanity check:

make test-unit

Development workflow

  1. Pick an issue or create one to discuss your change first
  2. Create a branch from main: git checkout -b feat/my-change
  3. Make changes with tests
  4. Run tests locally before committing
  5. Open a PR with a clear description
  6. Address review feedback if any

Branch naming:

Pattern Example
feat/<name> feat/add-gitea-support
fix/<name> fix/empty-repo-crash
docs/<name> docs/api-reference
chore/<name> chore/update-deps

Tests

Tests must pass before merge. CI enforces this automatically.

# Unit tests + vet (no Ollama needed — runs in CI)
make test-unit

# E2E pipeline tests (requires local or remote LLM)
make test-e2e

Integration tests use real Ollama with qwen3.5:latest. They create isolated git repos in t.TempDir() — they never touch the actual project repo.

Test targets

Command LLM required? What it runs
make test-unit / make test No Code vetting + standard unit tests (fast check)
make test-e2e Yes Commit pipeline & release E2E tests
make lint No Runs go vet static analysis

Project structure

git-courer/
├── cmd/main.go                   # Entry point
├── ffi/                          # Foreign-function interface bindings (tree-sitter)
├── internal/
│   ├── adapters/                 # Implementations of ports
│   │   ├── commitstore/          # Per-branch file-based commit plans
│   │   ├── confirm/              # In-memory safety locks
│   │   ├── git/                  # Git adapter & session redirect wrapper
│   │   ├── github/               # Optional PR client
│   │   ├── llm/                  # Unified OpenAI standard client
│   │   └── sessionstore/         # JSON session database
│   ├── classifier/               # Command-based Git change classification
│   │   └── gitcmd/               # Shell-command classifier (hook-check)
│   ├── config/                   # Config loading and defaults
│   ├── core/
│   │   ├── domain/               # Core logic (no external dependencies)
│   │   └── ports/                # Interfaces (Git, LLM, Confirm, Security)
│   ├── data/                     # Embedded language definitions
│   ├── delivery/
│   │   ├── cli/                  # CLI subcommand adapters (doctor, hook-check, release)
│   │   └── mcp/                  # MCP server and modular tool handlers
│   │       ├── descriptions/     # Per-tool MCP descriptions
│   │       └── shared/           # Shared MCP helpers (diff, formatters, progress)
│   ├── infra/
│   │   ├── chunkers/             # Diff and log chunkers
│   │   ├── classifier/           # AST-based classification via tree-sitter
│   │   ├── filters/              # Path filtering
│   │   └── secrets/              # Secret patterns, blacklist, magic bytes
│   ├── installer/                # Install, setup, and client configs
│   ├── models/                   # Local LLM capability detector
│   ├── security/                 # Multi-layer security service orchestrator
│   │   └── model.go              # Model-size gating (ParseModelSize) for LLM scan eligibility
│   ├── shared/prompts/           # Prompt templates
│   │   └── md/                   # Markdown prompt files
│   └── workflow/                 # Commit and release service workflows
├── tui/                          # Interactive terminal UI (Bubbletea)
│   ├── screens/                  # TUI screens
│   ├── components/               # Reusable TUI components
│   └── styles/                   # TUI styling
├── test/                         # E2E test suites
│   ├── pipeline/                 # Commit E2E pipeline tests
│   └── release/                  # Release E2E tests
└── docs/                         # Config, commands, and architecture guides

Architecture

Hexagonal architecture — ports in core/ports/, implementations in adapters/ and infra/. The core never imports from adapters.

delivery/mcp → workflow → core/ports ← adapters (git, llm, confirm)
                       ↓
                  core/domain

Commit conventions

type: short description (max 72 chars)

Optional body — explain WHY, not WHAT.

Types: feat fix refactor chore test docs perf ci

Breaking changes: add ! after type (feat!:) or BREAKING CHANGE: in the body.

Pull request process

  1. Branch from main
  2. Make changes with tests
  3. Run make test-unit (and make test-e2e if you changed LLM logic) — all must pass
  4. Open a PR using the PR template

PR checklist (required)

  • go build ./... compiles without errors
  • go test ./... unit tests pass
  • go vet ./... passes
  • Followed conventional commits
  • Updated documentation if applicable

If tests fail, the PR will not be merged. No exceptions.

Review process

  • PRs need at least one approval from a maintainer
  • All conversations must be resolved before merge
  • Stale reviews are dismissed automatically when new commits are pushed
  • Reviews focus on correctness, test coverage, and architecture fit

Prompt changes

Prompts live in internal/shared/prompts/md/. If you change one, run the E2E pipeline tests with your local LLM to see the actual model output:

go test -tags e2e ./test/pipeline/... -v -run TestCommit

Check the logged commit messages — they should describe purpose, not file names.

Reporting issues

Use GitHub Issues. Include:

  • OS and Go version
  • Ollama model (if relevant)
  • Steps to reproduce
  • Expected vs actual behavior

For security vulnerabilities, see SECURITY.md — do not open a public issue.

Getting help