Bash

Errata

For the purpose of this document, we will be considering an application called the "widget" application (go.pkg.littleman.co/widget). That application will contain an 'internal only' library called "foo" (go.pkg.littleman.co/widget/internal/foo).

There is an additional shared library called bar (go.pkg.littleman.co/bar). The design of libraries between "internal" and "shared" libraries should not vary, rather only their usage and, where possible, internal libraries should be made "sharable".

Packages

Naming

Go module names should be within the namespace:

  • go.pkg.littleman.co

For example,

  • go.pkg.littleman.co/widget

Dependency Management

All go programs should use the upstream "go modules" approach to vendor tooling.

Libraries

Third Party

The following libraries provide the canonical implementation of their respective problems.

Problem Library

CLI

github.com/spf13/cobra

Configuration

github.com/spf13/viper

Exit codes

github.com/dedelala/sysexits

Logging

golang.org/pkg/log

Metrics

go.opentelemetry.io

Tracing

go.opentelemetry.io

littleman.co

Layout

A library should consist of at least the following layout:

file purpose

api.go

Define the types that the user is expected to use

${NAME}.go

Define the entrypoint of the library (i.e. func New())

meta.go

Defines library meta information suitable for introspection by telemetry libraries.

Where ${NAME} is the name of the folder containing the package.

The file meta.go should contain:

package bar

// Version is this packages version, expressed as a "semantic version". See:
//
// - https://semver.org/
const Version = "0.0.0+dev"

// Name is the package fully qualified name (i.e. where it can be queried with `go get`).
const Name = "f/meta"

Where the Version is updated automatically as part of the library release process.

Interface over type

Unless that library exists for the sole purpose of establishing an interface (for example, open telemetry) than libraries should not depend on concrete implementations where possible, but rather interfaces that can be fulfilled with the above (or similar) libraries.

Linters

References

Found a bug? Got a correction? You can edit this page on GitHub