Skip to content

How GoCenter Works

Jump to bottom
Elio Marcolino edited this page Mar 20, 2020 · 3 revisions

How GoCenter Works

GoCenter hosts a fast central repository for immutable Go modules, building and validating Go modules and making them available on this public platform. On this page, you'll find the details on how modules end up in GoCenter and what happens with them there.

How modules get to GoCenter

We pre-populated GoCenter with tens of thousands of versions of the most popular Go libraries, and we are actively looking for more popular libraries to add. If you feel there is a library that needs to be in GoCenter, add it using the instructions below.

Adding modules from the UI

If a module is not found in GoCenter and you want to add it on the spot, you can add the module from the GoCenter UI.

Adding modules and versions

  1. Please search for your package first
  2. If you do not find your package (0 results), click the “Add” button under the search bar.
  3. Insert the fully qualified module name, e.g. k8s.io/client-go (note that this may vary from the project's GitHub URL, and you need to enter the canonical module import name)
  4. Click “Submit”
  5. You should receive a message indicating that it was accepted, or explaining the reason for not accepting it.
  6. If the module is accepted, GoCenter will start an automatic inclusion process (see below) for the latest 20 tags in the last year.
  7. Check back later to see that your request has been processed by searching for the package again.
  8. Once the package is found, you might see a 'Missing Versions' heading (in case the project has more than 20 tags in the last year).
  9. If you need one of the missing versions, click the green “Add Missing Versions” button.
  10. You should receive a message indicating that your request was accepted or explaining the reason for not accepting it.
  11. Check back later to see if your request has been processed.

Inclusion process

To ensure a minimal level of quality, a module must meet the inclusion criteria requirements before it can be added to GoCenter (see below).

Once the package is selected for inclusion in GoCenter (for any of the above reasons), GoCenter uses the project's go-import metadata to find the project's location.

If GoCenter discovers Go source files with a mod file, it packs the module and stores it in GoCenter. Otherwise, it will generate an empty go.mod, pack the module and store it in GoCenter.

Direct and transitive dependencies

In scenarios 1 and 2 above (if the project has dependencies, declared in any meaningful way), all the dependencies are parsed recursively using the same process.

Project inclusion criteria

  • Must be a public GitHub Repository
    • GitHub-compatible addresses like gopkg.in also work
    • Google repositories are covered through the dependency process and GoCenter internal requests (see above), but can't be included by users’ add requests.
  • Must be accessible via the GitHub API
    • If this criterion is a problem for you, please file a GitHub Issue, listing the domain and the provider you are using (for example many domains are actually using GitHub, so they're not a problem)
  • The GitHub project should have version tags in the v<semver> format, e.g., v1.0.0 as per the Go module standard. There should be new version tags created within the last year to ensure GoCenter doesn't pull in legacy tags. If no matching tags are found, GoCenter will consume the latest commit on the master branch.
    • As a general rule, once the master branch has been consumed as a v0.0.0-commit hash version, GoCenter will refuse new version requests. You should gently request the library owner to use version tagging as best practice.
    • If a project is a dependency of another project, GoCenter will consume any commit specified in the dependency, whether or not it meets the version specification criteria, and that dependency will be made available in GoCenter.
Clone this wiki locally