Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
202 lines (135 loc) · 5.01 KB

CONTRIBUTING.md

File metadata and controls

202 lines (135 loc) · 5.01 KB

Contributing to modkit

Thanks for your interest in contributing! modkit is in early development, so the best way to help is to coordinate with maintainers before large changes.

Getting Started

Prerequisites

  • Go 1.25.x (CI pinned to 1.25.7)
  • Docker (for running the example app)
  • Make

See the Stability and Compatibility Policy for toolchain and upgrade expectations.

Clone and Test

git clone https://github.com/go-modkit/modkit.git
cd modkit
go test ./...

Run the Example App

cd examples/hello-mysql
make run

Then test:

curl http://localhost:8080/health
curl http://localhost:8080/users

Setup Git Hooks

After cloning, ensure $GOPATH/bin is in your PATH:

# Add to your shell profile (.bashrc, .zshrc, etc.)
export PATH="$(go env GOPATH)/bin:$PATH"

Then run once to enable commit message validation:

make setup-hooks

This installs git hooks that validate commit messages follow Conventional Commits format:

<type>(<scope>): <short summary>

Examples:

  • feat: add user authentication
  • fix(http): handle connection timeout
  • docs: update installation guide

Valid types: feat, fix, docs, test, chore, refactor, perf, ci

Note: Commit message headers must be <=80 characters.

Development Workflow

Format Code

make fmt

Runs gofmt and goimports.

Lint

make lint

Runs golangci-lint. See .golangci.yml for configuration.

Vulnerability Check

make vuln

Runs govulncheck.

Run Tests

make test

Run CLI Smoke Checks

These are the same checks used by the CI cli-smoke job:

make cli-smoke-build
make cli-smoke-scaffold

Install Development Tools

make tools

make tools installs tool versions pinned by the repository.

Contribution Guidelines

Before You Start

  • Check existing issues to avoid duplicating work
  • For large changes, open an issue first to discuss the approach
  • Read the Architecture Guide to understand the codebase

Pull Request Process

  1. Fork the repository
  2. Update main and create a feature worktree branch:
    • git fetch origin && git switch main && git pull --ff-only origin main
    • git worktree add .worktrees/my-feature -b feat/my-feature main
    • Work from .worktrees/my-feature (do not commit on main)
  3. Make your changes with tests
  4. Run make fmt && make lint && make vuln && make test && make test-coverage
    • Also run CLI gate: make cli-smoke-build && make cli-smoke-scaffold
  5. Commit with a conventional prefix (feat:, fix:, docs:, chore:)
  6. Open a pull request with a clear description

Commit Prefixes

  • feat: — New feature
  • fix: — Bug fix
  • docs: — Documentation only
  • test: — Test changes
  • chore: — Build, CI, or tooling changes
  • refactor: — Code change that doesn't fix a bug or add a feature

Code Style

  • Follow Go formatting (gofmt)
  • Keep exported API minimal
  • Prefer explicit errors over panics
  • Write tests for new functionality

Code of Conduct

This project follows the Code of Conduct.

Good First Issues

New to modkit? Look for issues labeled good first issue for beginner-friendly tasks:

  • Documentation improvements
  • Test coverage
  • Example app enhancements
  • Bug fixes with clear reproduction steps

Questions?

Open an issue or start a discussion. We're happy to help!

Maintainer Operations

Maintainer triage targets, labeling flow, and adoption KPI cadence are documented in Maintainer Operations.

Releases

Releases are automated using Release Please.

How It Works

When changes are merged to main, Release Please updates or creates a release PR based on commit messages. Merging that release PR creates the version tag and GitHub Release:

Commit Type Release Action Example
feat: Minor version bump (0.1.0 -> 0.2.0) New API method
fix: Patch version bump (0.1.0 -> 0.1.1) Bug fix
feat!: or BREAKING CHANGE v0.x: minor bump; v1+: major bump Breaking API change
docs:, chore:, refactor:, test:, ci: No release Documentation, tooling

Versioning Strategy

modkit follows Semantic Versioning:

  • v0.x.x (current): API is evolving. Breaking changes (feat!:) bump the minor version (0.1.0 → 0.2.0) due to allow-initial-development-versions setting
  • v1.0.0 (future): Stable API with backward compatibility guarantees. Breaking changes will bump major version (1.0.0 → 2.0.0)
  • v2+: Major versions for breaking changes (requires /v2 import path)

Using a Specific Version

go get github.com/go-modkit/modkit@v0.1.0
go get github.com/go-modkit/modkit@latest