Skip to main content
This lesson explains a practical workflow and the recommended practices for developing, versioning, and publishing a Go module so other developers and Go tools can discover and consume it. A typical end-to-end workflow:
  1. Design and implement the packages and public API the module will expose.
  2. Commit the code to a repository using Go module conventions so the module path and tags are discoverable.
  3. Publish the module by tagging releases (semantic versions) so Go tools and proxies can fetch specific versions.
A dark presentation slide titled "Workflow" with three bullet points. It outlines: design and code the packages, commit code to a repository using Go conventions, and publish the module to make it discoverable.
Design and development guidance
  • Keep the module’s public API focused, cohesive, and discoverable. Organize packages and exported identifiers so users can find functionality quickly.
  • Aim for backward compatibility in minor and patch releases. When breaking changes are required, use semantic major versioning (see below) to signal the change to consumers.
  • Write meaningful documentation comments and examples; pkg.go.dev uses them to generate user-facing docs and improves module discovery.
A dark presentation slide titled "Design and Development" with two bullet points advising to keep a module's public API focused and discrete and to ensure backward compatibility. The header is highlighted in blue on a black background.
Publishing modules and versioning How Go discovers versions:
  • Go tools use the module path in go.mod together with VCS tags to locate and download a particular version. Module proxies (for example, the default GOPROXY) also mirror these tagged versions.
  • There is no centralized “upload” step: once the repository is reachable and properly tagged, go commands and proxies can fetch it.
  • After a version is published, the module and its documentation are typically visible on https://pkg.go.dev where developers can read docs and view source.
Common commands when releasing a version Example of tagging and pushing a release:
To consume that specific release:
Versioning rules to note
  • Use semantic versioning (MAJOR.MINOR.PATCH) to communicate compatibility:
    • Patch: backward-compatible bug fixes.
    • Minor: backward-compatible new features.
    • Major: incompatible API changes.
  • For major versions v2 and higher, the module path in go.mod must include the major version suffix. For example:
When you bump the major version to v2 or higher, ensure the module path in go.mod contains the /vN suffix (e.g., /v2). Tag releases with the corresponding semantic version (for example, v2.0.0) so Go tools resolve the correct import path and version.
Practical tips and common pitfalls
  • Always keep go.mod consistent with your intended import path. Mismatched module paths and tags prevent clients from resolving the correct version.
  • Use small, well-documented public APIs; users search by package and symbol names on sites like pkg.go.dev.
  • If you rely on private repositories, configure a GOPROXY or authentication that your consumers can use to fetch private modules.
  • Run go vet, go test, and golangci-lint (or similar) before tagging a release to reduce the chance of shipping regressions.
Further reading and references
A presentation slide titled "Versioning" that explains assigning version numbers to modules to signal stability and backward compatibility. It also notes you indicate a module's version by tagging its source in the repository.

Watch Video