About
Go.dev is a companion website to golang.org. Golang.org is the home of the open source project and distribution, while go.dev is the hub for Go users providing centralized and curated resources from across the Go ecosystem.
Go.dev provides:
- Centralized information for Go packages and modules published on index.golang.org.
- Essential learning resources
- Critical use cases & case studies
Go.dev is currently in MVP status. We’re proud of what we’ve built and excited to share it with the community. We hope you find value and joy in using go.dev. Go.dev only has a small portion of features we intend to build, and we are actively seeking feedback. If you have any ideas, suggestions or issues, please let us know.
Adding a package
Data for the site is downloaded from proxy.golang.org. We monitor the Go Module Index regularly for new packages to add to pkg.go.dev. If you don’t see a package on pkg.go.dev, you can add it by doing one of the following:
Visiting that page on pkg.go.dev, and clicking the “Request” button. For example:
https://pkg.go.dev/example.com/my/moduleMaking a request to proxy.golang.org for the module version, to any endpoint specified by the Module proxy protocol. For example:
https://proxy.golang.org/example.com/my/module/@v/v1.0.0.infoDownloading the package via the go command. For example:
GOPROXY=https://proxy.golang.org GO111MODULE=on go get example.com/my/module@v1.0.0
Removing a package
If you are the author of a package and would like to have it removed from pkg.go.dev, please file an issue on the Go Issue Tracker with the path that you want to remove.
Note that we can only remove a module entirely from the site. We cannot remove it just for specific versions.
Documentation
Documentation is generated based on Go source code downloaded from the Go Module Mirror at proxy.golang.org/<module>/@v/<version>.zip
. New module versions are fetched from index.golang.org and added to pkg.go.dev site every few minutes.
The guidelines for writing documentation for the godoc tool apply to pkg.go.dev.
It’s important to write a good summary of the package in the first sentence of the package comment. The go.dev site indexes the first sentence and displays it in search results.
Pkg.go.dev displays the GOOS and GOARCH for the documentation displayed at the bottom of the documentation page.
Best practices
Pkg.go.dev surfaces details about Go packages and modules in order to help provide guidelines for best practices with Go.
Here are the details we surface:
Has go.mod file
- The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go. A module version is defined by a tree of source files, with a go.mod file in its root. More information about the go.mod file.
Permissive license
- Permissive licenses place minimal restrictions on how software can be used, modified, and redistributed. For more information on how pkg.go.dev determines if a license is permissive, see our license policy.
Tagged version
- When the go get command resolves modules by default it prioritizes tagged versions. When no tagged versions exist, go get looks up the latest known commit. Modules with tagged versions give importers more predictable builds. See semver.org and Keeping Your Modules Compatible for more information.
Stable version
- Projects at v0 are assumed to be experimental. When a project reaches a stable version — major version v1 or higher — breaking changes must be done in a new major version. Stable versions give developers the confidence that breaking changes won’t occur when they upgrade a package to the latest minor version. See Go Modules: v2 and Beyond for more information.
Creating a badge
The pkg.go.dev badge provides a way for Go users to learn about the pkg.go.dev page associated with a given Go package or module. You can create a badge using the badge generation tool. The tool will generate html and markdown snippets that you can use on your project website or in a README file.
Adding links
You can add links to your README files and package documentation that will be shown on the right side of the pkg.go.dev page. For details, see this issue.
Keyboard Shortcuts
There are keyboard shortcuts for navigating package documentation pages. Type ‘?’ on a package page for help.
Bookmarklet
The pkg.go.dev bookmarklet navigates from pages on source code hosts, such as GitHub, Bitbucket, Launchpad etc., to the package documentation. To install the bookmarklet, click and drag the following link to your bookmark bar: Pkg.go.dev Doc
License policy
Information for a given package or module may be limited if we are not able to detect a suitable license. See our license policy for more information.
Feedback
Share your ideas, feature requests, and bugs on the Go Issue Tracker For questions, please post on the #tools slack channel on the Gophers Slack, or email the golang-dev mailing list.