A template repository for Go projects.
Starting a new project repository means to spend a lot of time first for setting up the basic structure and configuration for the used technology stack over and over again. It is a repetitive task since the same tools are often used across many projects, like linters and code formatters, and therefore often just copied over. This has the disadvantage that the configuration or documentation may differ between different projects or common changes and configurations are not synchronize at all. Many tools provide a way to created so called “shared configurations“ that can be used as base and dynamically composed with project-specific configurations, however, this does not apply to all. To prevent such problems a central place, so called “template repository“, for basic configurations and documentations as well as focus on different use cases, project structures and programming languages is a good solution to act as a single-source-of-truth™️.
tmpl-go, the imaginative abbreviation for “template Go“, is my solution to enable a smooth start for Go projects and ensure that a project stays healthy, stable and up-to-date over time. Thanks to Go's architecture and tooling this repository can be used as monorepo that can manage multiple Go & web applications or just a single Go module or package. No matter for what purposes it is used there are no significant changes needed to the repository structure. Please note that tmpl-go has mainly been created for my personal use in mind. The default configurations of this template might not fit your needs, but it was designed to be flexible and can be adapted to different use cases and environments.
This repository serves as a template for Go projects including basic tools and configurations with sane default values. It is built on top of the base tmpl repository which provides essential features for all kind of projects. Please see the tmpl project overview documentation for more details.
- Build on top of the base tmpl template repository that provides essential features for any project
- Extended configurations for GitHub specific features that are already provided in the base tmpl template repository:
- CI/CD action workflows for Go specific tasks
- Automated updates and security vulnerability alerts for Go Module and Yarn/npm dependencies through the native Dependabot integration
- Go Module to ensure a stable dependency management
- golangci-lint to check the Go code quality
See the “Features“ section below for more details.
The directory structure shown below is derived from the base tmpl template repository on which this project is based on. Please see the “Directory Structure“ section in the tmpl documentation for more details.
tmpl-go
├─ .github
│ ├─ ISSUE_TEMPLATE
│ └─ workflows
└─ assets
└─ images
The next directory structure shown below is specially designed for Go projects with monorepo layout where some parts were adapted from the golang-standards/project-layout and ardanlabs/service repositories while others are added through experience with own projects and inspiration from other large, production-grade and well-known projects of the Go ecosystem.
tmpl-go
├─ api
├─ apps
├─ config
├─ docs
├─ examples
├─ internal
├─ pkg
├─ test
└─ web
Please see the “Features“ section below for more details about provided files in this template repository. The detailed documentation about each directory is located in individual README.md files within the directory itself.
/api— The directory for API definition files like Protocol Buffers, JSON schemas or OpenAPI/Swagger specifications. See the dedicated/apidirectory documentation for more details and usage examples./apps— The directory for project application(s) using the Gomainpackage that can be compiled to the binary executable. See the dedicated/appsdirectory documentation for more details and usage examples./config— The directory for all configurations such as container orchestration deployments, templates for applications or distribution bundles. See the dedicated/configdirectory documentation for more details and usage examples./docs— The directory for project documentations, runbooks and any other kind of textual reference.. See the dedicated/docsdirectory documentation for more details and usage examples./examples— The directory for all configurations such as container orchestration deployments, templates for applications or distribution bundles. See the dedicated/examplesdirectory documentation for more details and usage examples./internal— The directory for non-exported (“private“) application and package code. See the dedicated/internaldirectory documentation for more details and usage examples./pkg— The directory for exported (“public“) APIs and package code. See the dedicated/pkgdirectory documentation for more details and usage examples./test— The directory for additional data and tools for automated testing. See the dedicated/testdirectory documentation for more details and usage examples./web— The directory for web specific data like SPAs, static websites, web components & packages or server-side rendered templates that are often built with JAMStack principles. See the dedicated/webdirectory documentation for more details and usage examples.
This repository serves as a template repository for Go projects that provides essential features.
The sections below contain more detailed information about each feature, the sane default configurations and their files in the repository as well as ways to customize and adjust them to adapt to other use cases and projects. They provide details about files in this repository and the overall directory structure.
This template repository has partially been designed for repositories hosted on GitHub and makes use of many of its fantastic features.
The GitHub Actions .github/workflows directory includes a basic CI/CD workflow files that run for changes in the Git main branch and v* tags. The lint-node job is derived from the tmpl template repository and runs all Node.js based linters that are also included in this template repository. The ci-go workflow runs all configured golangci-lint linters and the test job runs all tests with coverage report and enabled race detector.
To skip a workflow, include a supported keyword like [skip actions] in a commit message.
Next to the Dependabot configuration derived from the base tmpl template repository the dependabot.tmpl.yml file additionally additionally includes configurations for Go Module dependencies.
Make sure to read the tmpl template repository documentation about automated dependency updates to learn how to enable or disable Dependabot for a GitHub repository.
The go.mod and go.sum files contain information about the Go Module. See the official Go Module reference documentation, the “Modules“ page in the GitHub repository wiki and the “Create a Go module“ tutorial for more details.
To ensure a good code quality the Go ecosystem has hundreds of linters, each with a different purpose. Instead of installing and running multiple linters separately golangci-lint provides a uniform interface to run most popular and useful linters in parallel with many additional configuration features.
The actual runner is open source and can be used locally as well in any private CI/CD pipeline.
The .golangci.yml configuration file is located in the root of this template repository and comes with sane default configurations that can be simply adjusted and extended.
The runner is also used in the the existing CI GitHub action workflows through the golangci-lint-action GitHub action that has been created by the golangci-lint maintainers. See the “CI/CD Action Workflows“ section for more details.
There are multiple ways to use this template repository, either by using GitHubs feature to create a repository from a template or simply cloning it. No matter which method is used, there are a few manual steps to adjust some configurations and documentations for the individual target project. Note that these changes are only recommendations, but are common steps anyway.
- Follow the usage steps of the base tmpl repository.
- Adjust or delete the directories and their dedicated documentations of the “Directory Structure“ section to fit your project setup.
- Adjust the
go.modfile…- …so that the value of the
moduleattribute matches your projects Go Module name. - …so that the value of the
goattribute matches the Go version used by your project. - …by deleting the already defined
github.com/stretchr/testifymodule dependency when it is not used to write tests for your project.
- …so that the value of the
- Ensure the
go.sumfile matches thego.modfile by deleting it and runninggo mod tidyso Go resolves the dependency tree with the latest module versions.- …by editing it manually and remove entries of unused dependencies.
- Adjust or delete the
tmpl-go.goandtmpl-go_test.gofiles to match your project. - Adjust or delete the
workspacesfield of thepackage.jsonfile to match your project.
Next to the experience with own projects, many other large, production-grade and well-known projects of the Go ecosystem as well as the golang-standards/project-layout documentation about Go specific directories were used as references.
tmpl-go is an open source project and contributions are always welcome!
There are many ways to contribute, from writing- and improving documentation and tutorials, reporting bugs, submitting enhancement suggestions that can be added to tmpl-go by submitting pull requests.
Please take a moment to read the contributing guide to learn about the development process, the styleguides to which this project adheres as well as the branch organization and versioning model.
The guide also includes information about minimal, complete, and verifiable examples and other ways to contribute to the project like improving existing issues and giving feedback on issues and pull requests.
Copyright © 2020-present Sven Greb
