module-conventions

What problem does it solve?

This guide defines and enforces Go module conventions to ensure robust module paths, versioning, and dependency practices that prevent broken builds and inconsistent module histories.

Core Features & Use Cases

• Module Path Configuration: Ensure the module path in go.mod is the full repository import path, typically matching the repository URL.
• Go Version Management: Specify a minimum Go version in go.mod and pin exact toolchains with .go-version and toolchain directives.
• Dependency Management: Provide tidy/verify workflows, controlled upgrades with go get, and clear indirect/direct dependency handling.
• Package Organization & Versioning: Recommend cmd/internal/public structure, semantic versioning with v-prefix tags, and workspace guidance for multi-module repos.
• Use cases include initializing new projects, refactoring module paths, upgrading dependencies, and maintaining consistent module boundaries across teams.

Quick Start

Create a new Go module with a full repository path, set a minimum Go version, and scaffold the recommended directory structure.