Contributing to TableTest Formatter

July 17, 2026 · View on GitHub

Thank you for your interest in contributing to TableTest Formatter!

Project Structure

This is a multi-module Maven project with hexagonal architecture:

tabletest-formatter/
├── tabletest-formatter-core/       # Core formatting logic
└── tabletest-formatter-cli/        # Command-line interface

Module Responsibilities

  • tabletest-formatter-core: Pure formatting logic, depends on org.tabletest:tabletest-parser:1.2.0
  • tabletest-formatter-cli: Picocli-based CLI, creates uber JAR with maven-shade-plugin

Requirements

  • Java 17 or later
  • Maven 3.6+

Building

Build the entire project:

mvn clean install

Build a specific module:

mvn clean install -pl tabletest-formatter-core

Running Tests

Run all tests:

mvn test

Living documentation

The core module's @TableTest classes double as the formatter's specification. The opt-in report profile runs them with the TableTest reporter extension and generates an HTML report:

mvn -Preport -pl tabletest-formatter-core test org.tabletest:tabletest-reporter-maven-plugin:report

The report lands in tabletest-formatter-core/target/generated-docs/tabletest/. Until tabletest-reporter 1.1.1 is released, the profile needs the reporter installed locally (mvn install in the tabletest-reporter repo); the default build is unaffected.

Setting Up Your Development Environment

Git Hooks

This project uses custom git hooks for code quality and Beads for issue tracking.

Installation order (important!):

  1. Install custom hooks first:

    bash scripts/install-git-hooks.sh

  2. Then initialize Beads:

    bd init

    When prompted about git hooks, select "merge" to enable hook chaining.

What the hooks do:

  • pre-commit: Formats code with Spotless, runs full test suite, auto-restages modified files
  • pre-push: Prevents force-push to main/master branches
  • commit-msg: Validates conventional commit format, checks for Claude attribution

Development Workflow

Commit Message Format

Follow conventional commits:

  • feat: - New features
  • fix: - Bug fixes
  • docs: - Documentation changes
  • refactor: - Code refactoring
  • test: - Test changes
  • chore: - Build/tooling changes

Important: Omit Claude Code attribution footer (checked by commit-msg hook)

Working with Beads

Find available work:

bd ready           # Show issues ready to work (no blockers)
bd list --status=open  # All open issues

Start working on an issue:

bd show <id>       # Review issue details
bd update <id> --status=in_progress  # Claim it

Complete work:

bd close <id>      # Close completed issue
bd sync            # Sync with git remote

TDD Workflow

Follow the Red → Green → Refactor cycle:

  1. Write a failing test (Red)
  2. Write minimal code to pass (Green)
  3. Improve code structure (Refactor)
  4. Repeat

Testing guidelines:

  • Use @Test for single scenarios or complex setup
  • Use @TableTest for data-driven tests with multiple similar cases
  • See CLAUDE.md for detailed testing patterns

For detailed development guidelines, coding standards, and architectural decisions, see CLAUDE.md.

Code Formatting

The project uses Spotless with Palantir Java Format:

# Check formatting
mvn spotless:check

# Apply formatting
mvn spotless:apply

Pre-commit hooks automatically format code and run tests.

Project Documentation

  • README.md - User-facing documentation
  • CLAUDE.md - Detailed development notes and architectural decisions
  • CONTRIBUTING.md - This file (contributor guidelines)

Getting Help

  • Check existing issues in the GitHub repository
  • Review CLAUDE.md for architectural context
  • Open a new issue for bugs or feature requests