Black Lives Matter. Support the Equal Justice Initiative.

Developing and publishing modules

You can collect related packages into modules, then publish the modules for other developers to use. This topic gives an overview of developing and publishing modules.

To support developing, publishing, and using modules, you use:

See also

Workflow for developing and publishing modules

When you want to publish your modules for others, you adopt a few conventions to make using those modules easier.

The following high-level steps are described in more detail in Module release and versioning workflow.

  1. Design and code the packages that the module will include.
  2. Commit code to your repository using conventions that ensure it’s available to others via Go tools.
  3. Publish the module to make it discoverable by developers.
  4. Over time, revise the module with versions that use a version numbering convention that signals each version’s stability and backward compatibility.

Design and development

Your module will be easier for developers to find and use if the functions and packages in it form a coherent whole. When you’re designing a module’s public API, try to keep its functionality focused and discrete.

Also, designing and developing your module with backward compatibility in mind helps its users upgrade while minimizing churn to their own code. You can use certain techniques in code to avoid releasing a version that breaks backward compatibility. For more about those techniques, see Keeping your modules compatible on the Go blog.

Before you publish a module, you can reference it on the local file system using the replace directive. This makes it easier to write client code that calls functions in the module while the module is still in development. For more information, see “Coding against an unpublished module” in Module release and versioning workflow.

Decentralized publishing

In Go, you publish your module by tagging its code in your repository to make it available for other developers to use. You don’t need to push your module to a centralized service because Go tools can download your module directly from your repository (located using the module’s path, which is a URL with the scheme omitted) or from a proxy server.

After importing your package in their code, developers use Go tools (including the go get command) to download your module’s code to compile with. To support this model, you follow conventions and best practices that make it possible for Go tools (on behalf of another developer) to retrieve your module’s source from your repository. For example, Go tools use the module’s module path you specify, along with the module version number you use to tag the module for release, to locate and download the module for its users.

For more about source and publishing conventions and best practices, see Managing module source.

For step-by-step instructions on publishing a module, see Publishing a module.

Package discovery

After you’ve published your module and someone has fetched it with Go tools, it will become visible on the Go package discovery site at pkg.go.dev. There, developers can search the site to find it and read its documentation.

To begin using the module, a developer imports packages from the module, then runs the go get command to download its source code to compile with.

For more about how developers find and use modules, see Managing dependencies.

Versioning

As you revise and improve your module over time, you assign version numbers (based on the semantic versioning model) designed to signal each version’s stability and backward compatibility. This helps developers using your module determine when the module is stable and whether an upgrade may include significant changes in behavior. You indicate a module’s version number by tagging the module’s source in the repository with the number.

For more on developing major version updates, see Developing a major version update.

For more about how you use the semantic versioning model for Go modules, see Module version numbering.