Go Repository Template

This is a GitHub repository template for Go. It has been created for ease-of-use for anyone who wants to build binaries, Docker images, and publish Github releases.

It includes:

• build automation via Make,
• dependency management using Go Modules,
• linting with golangci-lint,
• unit testing with testify, race detector, code covarage HTML report using go-acc for accurate reporting,
• releasing using GoReleaser,
• dependencies scanning and updating thanks to Dependabot,
• Visual Studio Code configuration with Go and Remote Container support.

This work is based on the upstream Go Repository Template.

Usage

1. Click the Use this template button (alt. clone or download this repository).
2. Replace all occurences of mesosphere/golang-repository-template to your_org/repo_name in all files.
3. Rename folder cmd/seed to cmd/app_name and update .goreleaser.yml accordingly.
4. Update LICENSE and README.md.

Build and Test

Tip: to see all available make targets with descriptions, simply run make.

To run unit tests, run make test.

To run integration tests, run make integration-test.

To build development binaries (specified in .goreleaser.yml), run make build-snapshot This will output binaries in dist for all configured platforms.

To build a release snapshot locally (including all configured packages, etc in .goreleaser.yml), run make release-snapshot.

To build a full release, including publishing release artifacts, run make release.

To run any command inside the Docker container used in CI, run make docker run="make <target>".

To run seed command without building output binaries, run go run ./cmd/seed/main.go <subcommands_and_flags>

Release

CAUTION: Make sure to understand the consequences before you bump the major version. More info: Go Wiki, Go Blog.

Maintainance

Remember to update Go version in devcontainer.json.

Notable files:

• devcontainer.json - Visual Studio Code Remote Container configuration,
• .github/dependabot.yml - Dependabot configuration,
• .vscode - Visual Studio Code configuration files,
• .golangci.yml - golangci-lint configuration,
• .goreleaser.yml - GoReleaser configuration,
• Makefile - Make targets used for development, and .vscode/tasks.json,
• go.mod - Go module definition,
• tools.go - build tools.
• cmd - Commands and their respective subcommands, thin wrappers over the library code in pkg.
• pkg - All library code for this project.

FAQ

Why Visual Studio Code editor configuration

Developers that use Visual Studio Code can take advantage of the editor configuration. While others do not have to care about it. Setting configs for each repo is unnecessary time consuming. VS Code is the most popular Go editor (survey) and it is officially supported by the Go team.

You can always remove the .devcontainer and .vscode directories if it really does not help you.

How can I create a Docker image, deb/rpm/snap package, Homebrew Tap, Scoop App Manifest etc.

Take a look at GoReleaser docs as well as its repo how it is dogfooding its functionality.

How can I create a library instead of an application

You can change the .goreleaser.yml to contain:

build:
  skip: true
release:
  github:
  prerelease: auto

Alternatively, you can completly remove the usage of GoReleaser if you prefer handcrafted release notes.

Contributing

Simply create an issue or a pull request.