Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
155 lines (110 loc) · 4.38 KB

CONTRIBUTING.md

File metadata and controls

155 lines (110 loc) · 4.38 KB
Raw

Contributing to go-atlas

Thank you for your interest in contributing to go-atlas! This guide will help you get started.

Prerequisites

  • Go 1.25+ — download
  • Make — for running project targets
  • Git — for version control

Getting Started

  1. Fork the repository on GitHub.

  2. Clone your fork:

    git clone https://github.com/<your-username>/go-atlas.git
cd go-atlas

  3. Create a branch from develop:

    git checkout -b feat/my-feature develop

  4. Make your changes, then run checks:

    make fmt
make lint
make test-all

  5. Commit using Conventional Commits and push:

    git push origin feat/my-feature

  6. Open a Pull Request against the develop branch.

Branch Naming

Use the following prefixes:

Prefix Purpose
feat/ New features
fix/ Bug fixes
docs/ Documentation changes
refactor/ Code refactoring

Commit Messages

We follow Conventional Commits:

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

[optional body]

[optional footer(s)]

Types: feat, fix, docs, refactor, test, chore, ci, perf, build, style

Scope must match one of the allowed scopes in commit_scopes.txt. The scope represents the package or module affected by the change.

Examples:

feat(transport/grpc): add gRPC reflection support
fix(data/cache): handle nil pointer in Redis fallback
docs(README): add quick start examples
test(domain/converter): add benchmark for slice conversion
build(root): update Go version to 1.25

Automated Validation

  • GitHub Actions automatically validates all commit messages and PR titles
  • Local validation can be enabled with: git config core.hooksPath .githooks
  • Run .github/scripts/validate-commits.sh to check your commits before pushing

Code Style

Formatting

  • Run make fmt before committing — this runs gci with the project's import ordering.
  • Maximum line length: 156 characters (enforced by lll linter).

Import Ordering

Imports must follow this order (enforced by gci via .golangci.yml):

  1. Standard library
  2. Third-party packages (default)
  3. google.golang.org
  4. golang.org
  5. github.com/altessa-s/go-atlas
  6. github.com/altessa-s (other altessa packages)
  7. Blank imports
  8. Aliases

Copyright Headers

All .go files must include the copyright header. Run make copyright to add it automatically.

// Copyright 2021-2026 ALTESSA SOLUTIONS INC. All rights reserved.
// Use of this source code is governed by license that can be found in
// the LICENSE file.

Makefile Targets

Target Description
make fmt Format code and sort imports
make lint Run golangci-lint (34 linters)
make test Run all tests
make test-verbose Run tests with verbose output
make test-race Run tests with race detector
make test-shuffle Run tests with randomized order
make test-coverage Run tests with coverage report
make test-all Run tests with race, shuffle, and coverage
make test-coverage-func Per-package coverage breakdown
make bench Run all benchmarks
make bench-count Run benchmarks for benchstat
make dupl Find code duplication
make dupl-check Fail on code duplication
make copyright Add copyright headers
make generate Run go generate
make tidy Run go mod tidy
make security-scan Run govulncheck and gosec

Pull Request Process

  1. Ensure make lint and make test-all pass.
  2. Write conventional commit messages: release notes are generated from them by goreleaser at release time, there is no manually maintained CHANGELOG.md.
  3. Fill out the PR template completely.
  4. One approving review is required before merging.

Reporting Issues

License

By contributing, you agree that your contributions will be licensed under the MIT License.