Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
274 lines (188 loc) · 6.45 KB

CONTRIBUTING.md

File metadata and controls

274 lines (188 loc) · 6.45 KB

Contributing to Gentle AI

Thank you for your interest in contributing to Gentle AI (gga) — a Go TUI installer for AI agent environments.

Before you dive in, please read this guide fully. We have a structured workflow to keep the project organized and maintainable.

Table of Contents

Issue-First Workflow

No PR without an issue. No exceptions.

This project follows a strict issue-first workflow:

  1. Open an issue using the appropriate template (Bug Report or Feature Request)
  2. Wait for approval — a maintainer will add the status:approved label when the issue is ready to be worked on
  3. Comment on the issue to let others know you're working on it
  4. Open a PR referencing the approved issue

PRs that are not linked to an approved issue will be automatically rejected by CI.

Label System

Type Labels (applied to PRs)

Label Description
type:bug Bug fix
type:feature New feature or enhancement
type:refactor Code refactoring, no functional changes
type:docs Documentation only
type:test Test coverage additions
type:chore Build, CI, tooling changes
type:breaking Breaking change

Status Labels (applied to Issues)

Label Description
status:needs-review Newly opened, awaiting maintainer review
status:approved Approved for implementation — work can begin
status:in-progress Being worked on
status:blocked Blocked by another issue or external dependency
status:wont-fix Out of scope or won't be addressed

Priority Labels

Label Description
priority:critical Blocking issues, security vulnerabilities
priority:high Important, affects many users
priority:medium Normal priority
priority:low Nice to have

Development Setup

Prerequisites

  • Go 1.24+
  • Docker (for E2E tests)
  • Git

Clone and Build

git clone https://github.com/Gentleman-Programming/gentle-ai.git
cd gentle-ai
go build -o gga .

Run Locally

./gga

Testing

Unit Tests

Run the full unit test suite:

go test ./...

Run tests for a specific package:

go test ./internal/tui/...

Run with verbose output:

go test -v ./...

E2E Tests

E2E tests are Docker-based shell scripts. Docker must be running.

cd e2e
chmod +x docker-test.sh
./docker-test.sh

⚠️ E2E tests spin up containers to simulate real installation environments. They may take a few minutes to complete.

Commit Convention

This project uses Conventional Commits.

Commit messages must match this pattern:

^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\([a-z0-9\._-]+\))?!?: .+

Format

<type>(<optional-scope>)!: <description>

[optional body]

[optional footer]

Allowed Types

Type Purpose
feat New feature
fix Bug fix
docs Documentation only
refactor Code change (no behavior change)
chore Maintenance, dependencies, tooling
style Formatting, linting (no logic change)
perf Performance improvement
test Adding or updating tests
build Build system or external deps
ci CI configuration
revert Reverts a previous commit

Examples

feat(tui): add progress bar to installation steps
fix(agent): correct Claude Code detection on macOS
docs: update contributing guide
chore(deps): bump bubbletea to v0.26
refactor(pipeline): extract step executor
style: fix linter warnings in catalog package
perf(system): cache OS detection result
test(installer): add coverage for catalog step execution
build: update goreleaser config for arm64
ci: split unit and e2e test jobs
revert: undo model picker redesign

Breaking Changes

Add ! after the type/scope and include a BREAKING CHANGE: footer:

feat(cli)!: rename --config flag to --config-file

BREAKING CHANGE: the --config flag has been renamed to --config-file.
Update your scripts and aliases accordingly.

Breaking changes map to the type:breaking-change label.

Branch Naming

Branch names must match this pattern:

^(feat|fix|chore|docs|style|refactor|perf|test|build|ci|revert)\/[a-z0-9._-]+$

Rules:

  • All lowercase
  • Use hyphens, dots, or underscores as separators (no spaces, no uppercase)
  • Description must be short and descriptive

Examples: feat/user-login, fix/crash-on-startup, docs/api-reference, ci/add-e2e-job

Pull Request Rules

Before Opening a PR

  • There is a linked approved issue (Closes #<N>)
  • All unit tests pass (go test ./...)
  • E2E tests pass (cd e2e && ./docker-test.sh)
  • Commits follow Conventional Commits format
  • Code is self-reviewed

PR Title

Use the same Conventional Commits format as commit messages:

feat(tui): add keyboard shortcut help overlay
fix(agent): handle missing HOME env var gracefully

Automated PR Checks

All PRs go through automated checks:

Check What It Verifies
Check Issue Reference PR body contains Closes/Fixes/Resolves #N
Check Issue Has status:approved The linked issue has been approved by a maintainer
Check PR Has type: Label* Exactly one type:* label is applied
Unit Tests go test ./... passes
E2E Tests cd e2e && ./docker-test.sh passes

All checks must pass before a PR can be merged.

Linking Your Issue

In the PR body, include one of:

Closes #42
Fixes #42
Resolves #42

Code of Conduct

Be respectful. We're building something together.

  • Critique code, not people
  • Be constructive in reviews
  • Welcome newcomers

Violations may result in removal from the project.

Questions?

Use GitHub Discussions — not issues — for questions, ideas, and general conversation.