Go Repository Template

TEMPLATE INFORMATION

What is this?

This is a GitHub repository template for Go. It has been created for ease-of-use for anyone who wants to:

• quickly get into Go without losing too much time on environment setup,
• create a new repoisitory with basic Continous Integration.

It includes:

• continous integration via GitHub Actions,
• build automation via Make,
• dependency management using Go Modules,
• code formatting using gofumpt,
• linting with golangci-lint,
• unit testing with testify, race detector, code covarage HTML report and Codecov report,
• releasing using GoReleaser,
• dependencies scanning and updating thanks to Dependabot,
• security code analysis using CodeQL Action,
• Visual Studio Code configuration with Go and Remote Container support.

Star this repository if you find it valuable and worth maintaining.

Watch this repository to get notified about new releases, issues, etc.

How do I use it?

1. Sign up on Codecov and configure Codecov GitHub Application for all repositories.
2. Click the Use this template button (alt. clone or download this repository).
3. In GitHub
   1. Enable Issues
   2. Disable Allow merge commits and Allow squash merging
   3. Enable Always suggest updating pull request branches
   4. Enable Automatically delete head branches
   5. Enable Tags protection on *
   6. Set up the following branch protection rules on main:
      • Require a pull request before merging
      • Require approvals
      • Require review from Code Owners
      • Require status checks to pass before merging
      • Require branches to be up to date before merging
      • Status checks that are required
        • Analyze (go)
        • check-commit-message
        • ci (ubuntu-20.04)
        • codecov/patch
        • codecov/project
        • CodeQL
        • release-test
        • test (macos-10.15, 1.16)
        • test (macos-10.15, 1.17)
        • test (macos-10.15, 1.18)
        • test (ubuntu-20.04, 1.16)
        • test (ubuntu-20.04, 1.17)
        • test (ubuntu-20.04, 1.18)
        • test (windows-2019, 1.16)
        • test (windows-2019, 1.17)
        • test (windows-2019, 1.18)
      • Require linear history
   7. Allow all actions and reusable workflows
   8. Require approval for first-time contributors to Fork pull request workflows from outside collaborators
4. In the repository:
   1. Run make rename
   2. Replace all occurences of zdylag/GoSeed to your_org/repo_name in all files.
   3. Delete the following files:
      • DELETETHIS.go
      • DELETETHIS_test.go
   4. Update the following files:
      • CHANGELOG.md
      • CODE_OF_CONDUCT.md
      • CONTRIBUTING.md
      • LICENSE
      • README.md
   5. Make a pull request to start your new repo off right!

Setup

Below you can find sample instructions on how to set up the development environment. Of course you can use other tools like GoLand, Vim, Emacs. However take notice that the Visual Studio Go extension is officially supported by the Go team.

Local Machine

Follow these steps if you are OK installing and using Go on your machine.

1. Install Go.
2. Install Visual Studio Code.
3. Install Go extension.
4. Clone and open this repository.
5. F1 -> Go: Install/Update Tools -> (select all) -> OK.

Development Container

Follow these steps if you do not want to install Go on your machine and you prefer to use a Development Container instead.

1. Install Visual Studio Code.
2. Follow Developing inside a Container - Getting Started.
3. Clone and open this repository.
4. F1 -> Remote-Containers: Reopen in Container.
5. F1 -> Go: Install/Update Tools -> (select all) -> OK.

The Development Container configuration mixes Docker in Docker and Go definitions. Thanks to it you can use go, docker, docker-compose inside the container.

Build

Terminal

• make - execute the build pipeline.
• make help - print help for the Make targets.

Visual Studio Code

F1 → Tasks: Run Build Task (Ctrl+Shift+B or ⇧⌘B) to execute the build pipeline.

Release

The release workflow is triggered each time a tag with v prefix is pushed.

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

How to automate generating git tags for next release version

Auto-tagging can be done in many ways e.g. by using GitHub Actions like:

• Github Tag Bump,
• bumpr,
• Increment Semantic Version,
• Github Tag.

However, creating a release tag manually is often the optimal approach. Take notice that this template executes a release workflow each time a git tag with v prefix is pushed.

Contributing

Simply create an issue or a pull request.