When you're developing modules to publish for others to use, you can help ensure that your modules are easier for other developers to use by following the repository conventions described in this topic.
This topic describes actions you might take when managing your module repository. For information about the sequence of workflow steps you'd take when revising from version to version, see Module release and versioning workflow.
Some of the conventions described here are required in modules, while others are best practices. This content assumes you're familiar with the basic module use practices described in Managing dependencies.
Go supports the following repositories for publishing modules: Git, Subversion, Mercurial, Bazaar, and Fossil.
For an overview of module development, see Developing and publishing modules.
In Go‘s decentralized system for publishing modules and retrieving their code, you can publish your module while leaving the code in your repository. Go tools rely on naming rules that have repository paths and repository tags indicating a module’s name and version number. When your repository follows these requirements, your module code is downloadable from your repository by Go tools such as the go get command.
When a developer uses the go get command to get source code for packages their code imports, the command does the following:
import statements in Go source code, go get identifies the module path within the package path.go get locates the latest release version.You can keep maintenance simple and improve developers' experience with your module by following the conventions described here. Getting your module code into a repository is generally as simple as with other code.
The following diagram illustrates a source hierarchy for a simple module with two packages.
Your initial commit should include files listed in the following table:
From the command-line, you can create an empty repository, add the files that will be part of your initial commit, and commit with a message. Here's an example using git:
$ git init $ git add --all $ git commit -m "mycode: initial commit" $ git push
You publish code in a module when the code should be versioned independently from code in other modules.
Designing your repository so that it hosts a single module at its root directory will help keep maintenance simpler, particularly over time as you publish new minor and patch versions, branch into new major versions, and so on. However, if your needs require it, you can instead maintain a collection of modules in a single repository.
You can maintain a repository that has a single module's source in it. In this model, you place your go.mod file at the repository root, with package subdirectories containing Go source beneath.
This is the simplest approach, making your module likely easier to manage over time. It helps you avoid the need to prefix a module version number with a directory path.
You can publish multiple modules from a single repository. For example, you might have code in a single repository that constitutes multiple modules, but want to version those modules separately.
Each subdirectory that is a module root directory must have its own go.mod file.
Sourcing module code in subdirectories changes the form of the version tag you must use when publishing a module. You must prefix the version number part of the tag with the name of the subdirectory that is the module root. For more about version numbers, see Module version numbering.
For example, for module example.com/mymodules/module1 below, you would have the following for version v1.2.3:
example.com/mymodules/module1module1/v1.2.3example.com/mymodules/module1/package1example.com/mymodules/module1 module1/v1.2.3