Contributing to go-common

Thank you for your interest in contributing to go-common!

Development Setup

Prerequisites

• Go 1.24+ - Download
• golangci-lint - Static analysis
• lefthook - Git hooks manager
• commitizen - Conventional commit helper

Quick Setup

Run the setup script to install dependencies and configure git hooks:

./scripts/dev-setup.sh

Manual Setup

If you prefer to set up manually:

# Install golangci-lint
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

# Install lefthook
go install github.com/evilmartians/lefthook@latest

# Install commitizen (choose one)
pipx install commitizen
# OR
pip install --user commitizen

# Install actionlint (optional, for GitHub workflow linting)
go install github.com/rhysd/actionlint/cmd/actionlint@latest

# Install git hooks
lefthook install

# Verify setup
go mod download
go mod verify

Commit Message Convention

This project uses Conventional Commits. All commit messages must follow this format:

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Types

• feat - New feature
• fix - Bug fix
• docs - Documentation only
• style - Code style (formatting, semicolons, etc.)
• refactor - Code refactoring
• perf - Performance improvement
• test - Adding or updating tests
• build - Build system or dependencies
• ci - CI/CD configuration
• chore - Maintenance tasks

Scopes

Scope	Description
cmd	CLI utilities (cmd/)
envfile	Environment file parsing (envfile/)
ghsecrets	GitHub secrets handling (ghsecrets/)
logging	Logging utilities (logging/)
path	Path utilities (path/)
yaml	YAML utilities (yaml/)
deps	Dependency updates
ci	CI/CD workflows
docs	Documentation

Examples

git commit -m "feat(logging): add JSON output format"
git commit -m "fix(envfile): handle empty lines correctly"
git commit -m "docs: update README with usage examples"
git commit -m "chore(deps): update gopkg.in/yaml.v3 to v3.0.2"

Using Commitizen

For an interactive commit helper:

cz commit

Git Hooks

Lefthook manages the following git hooks:

Pre-commit

Runs on every commit:

• gofmt - Formats Go code (auto-fixes)
• go vet - Static analysis
• golangci-lint - Extended linting
• actionlint - GitHub workflow validation

Commit-msg

Validates commit message format using commitizen.

Pre-push

Runs before pushing:

• commitizen-range - Validates all commits since upstream
• go build - Ensures code compiles
• go test - Runs all tests with race detection
• go mod verify - Validates module checksums

Running Hooks Manually

# Run all pre-commit hooks
lefthook run pre-commit

# Run all pre-push hooks
lefthook run pre-push

# Run a specific hook
lefthook run pre-commit --commands gofmt

Code Style

• Follow standard Go conventions
• Run gofmt -s -w . before committing
• Ensure all exported functions have documentation comments
• Keep functions focused and reasonably sized

Testing

# Run all tests
go test ./...

# Run tests with race detection
go test -race ./...

# Run tests with coverage
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

Pull Request Process

1. Fork the repository
2. Create a feature branch (git checkout -b feat/my-feature)
3. Make your changes
4. Ensure all hooks pass (lefthook run pre-commit && lefthook run pre-push)
5. Push to your fork
6. Open a Pull Request

Questions?

Open an issue if you have questions or need help.