Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
66 lines (49 loc) · 3.65 KB

CONTRIBUTING.md

File metadata and controls

66 lines (49 loc) · 3.65 KB
Raw

Contributing to Kokomo

Welcome! This document provides the essential guidelines, conventions, and workflows required to contribute to the Kokomo project.

Core Philosophy

Kokomo is a tool designed to augment the Go experience through precision code generation. Every contribution should prioritize:

  • Minimalism: Only add what is necessary.
  • Precision: Respect the AST and ensure generated code is idiomatic.
  • Safety: Maintain the semantic integrity of the host package.

Project Conventions

Architecture & Visibility

  • Main Entry: The main package is at the repository root. It should only call internal/cli/root.Run().
  • Encapsulation: Use the internal/ directory for all implementation details. Only the following are exported:
    • pkg/astutil
    • The plugin interface definitions.
    • Functions/methods used for registering new plugins.
  • Immutability: Prefer immutable types whenever possible.

Development & Testing

  • Style Guide: All code must conform to the Uber Go Style Guide.
  • Commit Messages: Use Conventional Commits (e.g., feat:, fix:, docs:, refactor:).
  • Unit Testing:
    • Use blackbox testing.
    • For a file foo.go, place tests in foo_test.go using package foo_test.
  • Integration Testing:
    • Tests must cover a complete package hierarchy.
    • Use the gotest.tools/v3/golden package to compare generated files against "golden" snapshots.
  • Validation: Utilize field tags and github.com/go-playground/validator/v10 for data validation.

Development Workflow

To maintain code quality and automated release integrity, all changes must follow this cycle:

  1. Local Development: Write code and run tests locally. Ensure all pre-commit hooks pass.
  2. Pull Requests: All changes must be submitted via a Pull Request. Use Squash merge for all Pull Requests. Direct commits to the main branch are prohibited.
  3. Conventional Commits: Your PR commits must follow the Conventional Commits specification. This is critical because release-please uses these commit messages to automatically generate the changelog and determine version bumps (e.g., feat: triggers a minor bump, fix: triggers a patch).
  4. Review: Once a PR is opened, it will undergo automated linting and human review.

Release Process

Kokomo uses an automated release process driven by release-please:

  1. Automated PRs: When you merge a PR that follows Conventional Commits, release-please will automatically create a "Release PR."
  2. Changelog Generation: This Release PR will contain the updated CHANGELOG.md with your changes categorized.
  3. Finalizing: Merging the Release PR triggers the creation of a GitHub Release and a new Git Tag (e.g., v0.1.0).

Plugin Development Workflow

Adding a new plugin follows these steps:

  1. Requirement Analysis: Define the target boilerplate and necessary AST inputs (fields, tags, etc.).
  2. Implementation:
    • Implement the logic as a cobra.Command.
    • Use pkg/astutil to parse the target AST node.
    • Use the jen package for all code generation. Never manually concatenate strings to build Go code.
    • Append code to the end of the generated file.
  3. Testing:
    • Write unit tests for your parsing logic.
    • Write integration tests that validate the output against a golden file.

Tooling

We use asdf for version management and pre-commit for linting. Ensure you have run asdf install and pre-commit install --install-hooks before submitting your first PR.