svengreb/tmpl-go

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.

Overview

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.

Directory Structure

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 /api directory documentation for more details and usage examples.
/apps — The directory for project application(s) using the Go main package that can be compiled to the binary executable. See the dedicated /apps directory 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 /config directory documentation for more details and usage examples.
/docs — The directory for project documentations, runbooks and any other kind of textual reference.. See the dedicated /docs directory 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 /examples directory documentation for more details and usage examples.
/internal — The directory for non-exported (“private“) application and package code. See the dedicated /internal directory documentation for more details and usage examples.
/pkg — The directory for exported (“public“) APIs and package code. See the dedicated /pkg directory documentation for more details and usage examples.
/test — The directory for additional data and tools for automated testing. See the dedicated /test directory 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 /web directory documentation for more details and usage examples.

Features

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.

GitHub

This template repository has partially been designed for repositories hosted on GitHub and makes use of many of its fantastic features.

CI/CD Action Workflows

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.

Automated Dependency Updates

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.

Go Module

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.

Go Code Quality Linting

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.

Usage

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.mod file…
- …so that the value of the module attribute matches your projects Go Module name.
- …so that the value of the go attribute matches the Go version used by your project.
- …by deleting the already defined github.com/stretchr/testify module dependency when it is not used to write tests for your project.
Ensure the go.sum file matches the go.mod file by deleting it and running go mod tidy so 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.go and tmpl-go_test.go files to match your project.
Adjust or delete the workspaces field of the package.json file to match your project.

References

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.

Contributing

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.

svengreb / tmpl-go