Skip to content

Latest commit

 

History

History
155 lines (117 loc) · 4.64 KB

CONTRIBUTING.md

File metadata and controls

155 lines (117 loc) · 4.64 KB

Contributing to gittrace

Thank you for your interest in contributing to gittrace! This document provides guidelines and instructions for contributing to the project.

Code of Conduct

By participating in this project, you agree to abide by our Code of Conduct. Please read it before contributing.

How to Contribute

Reporting Bugs

If you find a bug, please open an issue with:

  • A clear, descriptive title
  • Steps to reproduce the issue
  • Expected behavior vs actual behavior
  • Your environment (OS, Java version, Git version)
  • Any relevant error messages or logs

Suggesting Features

We welcome feature suggestions! Please open an issue with:

  • A clear description of the feature
  • Use cases and examples
  • Why this feature would be useful
  • Any implementation ideas (optional)

Pull Requests

  1. Fork the repository and clone your fork

  2. Create a branch for your changes:

    git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix

  3. Make your changes:

    • Follow the existing code style
    • Add tests if applicable
    • Update documentation as needed
    • Keep commits focused and atomic

  4. Test your changes:

    ./gradlew clean build
./gradlew test  # Run all unit tests
./gradlew test --tests "*EndToEndTest.end-to-end test with -fl option"  # Run end-to-end test
./gittrace -fl="src/main/kotlin/dev/gittrace/Main.kt:1"  # Test with your changes

  5. Commit your changes:

    • Write clear, descriptive commit messages
    • Reference issue numbers if applicable (e.g., "Fix #123: ...")

  6. Push to your fork:

    git push origin feature/your-feature-name

  7. Open a Pull Request:

    • Provide a clear description of your changes
    • Reference any related issues
    • Wait for review and address feedback

Development Setup

Prerequisites

  • JDK 17–24 (Java 25 has Kotlin compiler compatibility issues)
  • Git
  • Gradle (wrapper included)

Building the Project

# Clone the repository
git clone https://github.com/yourusername/gittrace.git
cd gittrace

# Build the project
./gradlew build

# Run tests (if any)
./gradlew test

# Install locally
./install.sh

Project Structure

gittrace/
├── src/main/kotlin/dev/gittrace/
│   ├── Main.kt           # CLI entry point, Clikt command
│   ├── LocationParser.kt # Parses "file:line" format
│   ├── GitBlame.kt       # Runs git blame, error handling
│   ├── GitParallel.kt    # Parallel git commands for perf
│   ├── PorcelainParser.kt# Parses git blame --porcelain output
│   ├── CommitFormatter.kt# Orchestrates formatting
│   ├── HumanFormatter.kt # Human-readable output
│   ├── JsonFormatter.kt  # JSON output (aligned schema)
│   ├── FormatterUtils.kt # Shared time/range formatting
│   ├── Constants.kt      # UNCOMMITTED_HASH, etc.
│   ├── FormatOptions.kt  # JSON output options
│   ├── GitLinks.kt       # Git ops, commit/PR URLs
│   └── BlameEntry.kt     # Data model for blame lines

Coding Guidelines

Kotlin Style

  • Follow Kotlin coding conventions: https://kotlinlang.org/docs/coding-conventions.html
  • Use meaningful variable and function names
  • Keep functions focused and small
  • Add comments for complex logic
  • Use internal visibility for functions that shouldn't be public API

Code Formatting

  • Use consistent indentation (4 spaces)
  • Keep lines under 120 characters when possible
  • Use trailing commas in multi-line lists/arguments

Testing

  • Write tests for new features and bug fixes
  • Ensure all tests pass before submitting PR (./gradlew test)
  • Run end-to-end test: ./gradlew test --tests "*EndToEndTest.end-to-end test with -fl option"
  • Test edge cases and error conditions
  • Generate coverage report: ./gradlew jacocoTestReport
  • View coverage report: build/reports/jacoco/test/html/index.html
  • Aim for at least 60% code coverage (enforced by build)

Areas for Contribution

We welcome contributions in these areas:

  • Performance improvements: Optimize git command execution, caching, etc.
  • New features: Additional output formats, integrations, etc.
  • Documentation: Improve README, add examples, tutorials
  • Testing: Add unit tests, integration tests
  • Bug fixes: Fix reported issues
  • Platform support: Improve Windows/macOS/Linux compatibility
  • CI/CD: Set up GitHub Actions, automated testing

Questions?

If you have questions about contributing, feel free to:

  • Open an issue with the question label
  • Check existing issues and discussions

Thank you for contributing to gittrace! 🎉