All code in this repo should be written in Go, Shell or Make. Exceptions are made for things under
examples because we want to be able to give people examples of using the product in other languages. And for things like
doc/conf.py which configures an outside tool we want to use for docs. However in choosing outside tooling we prefer tools that we can interface with entirely using Go. Go's new enough that it's not always possible to find such a tool so we expect to make compromises on this. In general you should operate under the assumption that code written in Go, Shell or Make is accessible to all developers of the project and code written in other languages is accessible to only a subset and thus represents a higher liability.
- Scripts should work on macOS as well as Linux.
Go has pretty unified conventions for style, we vastly prefer embracing these standards to developing our own.
- We have several Go checks that run as part of CI, those should pass. You can run them with
- Go Code Review Comments
- Effective Go
- Command-line flags should use dashes, not underscores.
- Please consider package name when selecting an interface name, and avoid redundancy.
storage.Interfaceis better than
- Do not use uppercase characters, underscores, or dashes in package names.
- Unless there's a good reason, the
package fooline should match the name of the directory in which the .go file exists.
- Importers can use a different name if they need to disambiguate.
- Locks should be called
lockand should never be embedded (always
lock sync.Mutex). When multiple locks are present, give each lock a distinct name following Go conventions -
- All new packages and most new significant functionality must come with test coverage
- Avoid waiting for asynchronous things to happen (e.g. waiting 10 seconds and assuming that a service will be afterward). Instead you try, wait, retry, etc. with a limited number of tries. If possible use a method of waiting directly (e.g. 'flush commit' is much better than repeatedly trying to read from a commit).
Go Modules/Third-Party Code¶
- Go dependencies are managed with go modules (as of 07/11/2019).
- To add a new package or update a package. Do:
go get fooor for a more specific version
go get firstname.lastname@example.org,
go get foo@master,
go get foo@e3702bed2
- import foo package to you go code as needed.
Note: Go modules requires you clone the repo outside of the
$GOPATHor you must pass the
GO111MODULE=onflag to any go commands. See wiki page on activating module support
See The official go modules wiki for more info.
PRs for code must include documentation updates that reflect the changes that the code introduces.
When writing documentation, follow the Style Guide conventions.
PRs that have only documentation changes, such as typos, is a great place to start and we welcome your help!
For most documentation PRs, you need to
make assetsand push the new
assets.gofile as well.