A batteries-included project generator for your next Go project :rocket:

notsatan, updated 🕥 2022-07-07 15:02:42

go-template

TL;DR

cookiecutter gh:notsatan/go-template

OR

cookiecutter https://github.com/notsatan/go-template

And you're good to go! Jump to the setup section directly for quick setup instructions ;)

:boom: Features

This is a battries-included cookiecutter :cookie: template to get you started with the essentials you'll need for your next Go project ;)

Development

• Supports Go v1.16, v1.17 and v1.18
• Automated code formatting with gofmt and gofumpt
• Sort imports with goimports and gci
• Ready to use pre-commit setup, complete with a ton of hooks already configured in .pre-commit-config.yaml
• Security checks with gosec, code duplication checks with dupl, magic number checks with go-mnd
• Configured .editorconfig, .dockerignore and .gitignore - you won't have to bother with trivialities
• Enforce good programming practices with go-critic, gocyclo, gocognit and stylecheck
• Code linting with golangci-lint, complete with a ready-to-run .golangci.yml configuration file
• Easy setup with Makefile - run linters, check for codestyle, run tests and generate coverage reports - all with a single command
• Multiple test modes supported by the Makefile - allowing you run tests as frequently as you need, without having to run long tests (>20 sec) everytime (ugh).

Deployment

• Github Actions with predefined workflows including CI/CD, release drafter and optional code coverage with Codecov
• All Github actions can be run manually if needed
• A simple Dockerfile with multi-stage build to containerize your apps while ensuring smallest possible image sizes
• Always up-to-date dependencies with @Dependabot - enabled by default, remove dependabot.yml to disable!
• A simple shell script to generate compiled binaries for multiple OS/architectures with checksums for verification
• Automated release management with Release Drafter, pre-configured to handle the default Github labels (and more) through release-drafter.yml

Community

• Ready to use pull request and issue templates out of the box
• Files such as LICENSE, CONTRIBUTING.md, CODE_OF_CONDUCT.md, and SECURITY.md will be generated automatically.
• Semantic Versions specifications with Release Drafter
• Fork friendly - projects generated through go-template use relative links. Forks link to themselves instead of your project -- even for soft forks, ensuring there are no confused users!

:microscope: Setup Instructions

Installation

To start using the template, install the latest version of Cookiecutter (make sure you have Python and pip installed)

sh pip install -U cookiecutter

Once you have cookiecutter installed, move over to the directory where you want to generate your project and run

sh cookiecutter gh:notsatan/go-template

Alternatively, you can achieve the same results with the command

sh cookiecutter https://github.com/notsatan/go-template/

Input Variables

Cookiecutter will ask you to fill some variables that will be used to generate your project from this template. This section lists all the input variables, their default values, and what they are used for

Quick Note: Cookiecutter needs all inputs to have a default value. Many of the defaults for the setup resort to this repository (for example, the module path points to this Github repository, license owner name refers to me, etc)

These defaults must be filled with actual values during the setup!

| Parameter | Default Value | Usage | |----------------------------|-------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | project_name | example-project | Name of the project. A directory of this name will be created in the current working directory | | project_description | Based on project_name | A small description of the project, used to generate GNU license file, and default readme | | go_module_path | Based on project_name | Complete Go module path for the generated project, use a valid Github URL to enable Github specific features | | license_owner | example | Used in LICENSE and other files. Can be the name of a person or an organization. | | base_branch | master | The stable/base branch. Used for build status badges and release-drafter (if you enable Github specific features) | | contact_email | "" | Email to get in touch with project stakeholders. CODE_OF_CONDUCT.md and SECURITY.md will be removed if empty. Why is this needed? | | github_specific_features | y | Yes or No (y or n). Dictates if Github-specific features should be included in the project (issue templates, pipeline, etc). More Info | | use_codecov | y | Yes or No (y or n). Decides if Codecov is to be used in the project or not. Checkout Setting up codecov | | use_precommit | y | Yes or No (y or n). Decides if pre-commit configs should be included with the generated templates | | go_version | 1.17 | The version of Go to use in the project. Can be either 1.16, 1.17 or 1.18 | | license | MIT | The license you want to use in the generated project. One of MIT, BSD-3, GNU GPL v3.0 and Apache Software License 2.0 |

All values entered while setting up the Cookiecutter template will be saved in cookiecutter-config-file.yml, you can refer to them in the generated project :wink:

Important: Go through this section if you're creating a project that will be owned by a Github organization

Post Installation

When Cookiecutter completes generating your project, move into the project directory. Let the Makefile install and setup the resources needed for the project to run locally, use

sh make local-setup

Once the Makefile command is done with the setup, be sure to install GolangCI-Lint (this won't be handled by the Makefile command). GolangCI is used to run a bunch of linters on your code, when integrated with the pre-commit config file, this would ensure multiple linters are automatically run on your codebase with every commit - and optionally every push to the remote if you have enabled the linter action

Head over to the GolangCI-Lint website for installation instructions. And that's it. You should have your own project up and running by now :)

:dart: What's Next

Start playing around with the generated template :')

If you're a beginner with Go, I would like to recommend some articles, blogs and other resources that helped me learn Go - these will (hopefully) be of some help to you

• Go Official Docs: For Go, the official documentation is an excellent place to start learning. Highly recommened resource for beginners.
• Effective Go: A blog post that is a part of the official documentation, yet important enough to be a separate point by itself! Gives you an in-depth idea of how to structure and write your Go code. Recommended read once you've learnt the basics of Go
• Uber's Style Guide for Go: Slightly opionated at times, a great resource nevertheless. Gives a very detailed look at what "bad" Go code is, and how to rewrite it to be simpler and more effective. Recommended read for people with some experince in using Go (less so for people with no experience)
• Go Code Review Comments: A part of the Go Wiki, can be seen as a supplement to Effective Go (mentioned above)
• 50 Shades of Go: A collection of common traps and gotcha's for Go devs! Recommended read once you start writing code in Go, not recommended for complete newbies - can potentially drown you with excess information

General

Articles and resources which were of great help to me when making this template

• Github Actions Documentation
• Docker Multi-Stage Build Docs
• Docs for codecov.yml
• GolangCI-Lint Configuration Docs

:interrobang: FAQ

Why is my Email ID needed?

Like all other fields, the contact_email field is also optional. You can choose to leave this value blank, and the template will work normally.

The email field is used to generate CODE_OF_CONDUCT.md and SECURITY.md — both of which require people to get in touch with project stakeholders directly, either to report a violation, or a bug!

Note: If you choose to leave the email field blank, neither SECURITY.md nor CODE_OF_CONDUCT.md will be generated by the template! Since both of these files require people to get in touch directly, not having an email ID makes these files be redundant. If you still want these files, you can manually add them to the generated project!

What does the github_specific_features field do?

Not every project generated using this template needs to be hosted on Github. There are many other Git hosting-providers out there, each of them as valid as Github.

At the same time, Github happens to be the most popular code hosting platform - as such, projects generated by go-template include a lot of features that would ensure a very smooth development experience on Github, but would be redundant anywhere outside Github. Some examples of this would be Github pipelines, Github actions, issue templates, pull request templates, and more.

In case you do not plan to use Github as a code-hosting platform for your project, you can use this field to ensure the generated project is free of Github-specific files/code.

Note: If Github specific features are required, the value of go_module_path should be a path to a Github repository (does not matter if it exists). This would be used for dependabot.yml

How to integrate Codecov for automated code analysis?

Codecov is a code analysis tool, go-template can generate a project with pre-configured support for Codecov code analysis. With Codecov enabled, the CI pipeline will generate a code coverage report everytime tests are run.

Note: The process listed here depends on Github workflows, as such, if you choose not to use Github features (through the github_specific_features field), or to not use Codecov (through the use_codecov field) - you'll have to figure this bit yourself!

Follow Codecov Docs to activate Codecov for your project repository.

Once you've activated Codecov for your project, you should be able to see the Repository Upload Token. Copy this token, and add it as a secret to your Github repository.

The name of the secret should be "CODECOV_TOKEN" (no spaces, copy-paste the string as it is). The value of the secret would be the Repository Upload Token obtained from Codecov.

Save this secret and you're done with setting up Codecov, code coverage reports should be available with the next run of the CI pipeline.

How to fix ValueError: Attempt to enable Github-specific features when module path does not belong to github?

This error would be thrown when you chose to enable Github specific features, but, the Go module path you used does not match against Github. Currently, go-template uses the following regex expression to validate module paths

regex ^github.com\/[a-zA-Z0-9\-]+\/[a-zA-Z0-9\-]+\/?$

This check is needed is to ensure the dependabot.yml config will add the repository owner as a reviewer whenever dependabot raises a pull request for a dependency update.

How do I configure dependabot for Github organizations?

By default, if you choose to enable Github features, the dependabot.yml config file will use the Go module path to figure out the owner of the repostiory, and assign any pull request raised to the repository owner

In simpler terms, if the Go module path is

sh github.com/notsatan/go-template

Any pull request raised by dependabot will assign notsatan (me) as the reviewer.

While this works well for normal users, at the same time, for organizations, dependabot will try to assign pull requests to the entire organization!

To fix this, once the project is generated, simply edit the dependabot.yml file and modify the values under reviewers and assignees.

:heavy_check_mark: TODOs

Stuff that's in the plan - contributions are welcome! Please raise an issue before you start working (especially if you're picking up one of these tasks);

• [ ] Integrating goreleaser - Automated releases sure sounds cool!
• [ ] Minor improvements to .golangci.yml - The generated file should be enough to give users (developers) a rough idea of configs.
• [ ] Possible integration with mkdocs-material for projects that need a documentation. Should definitely be optional though!
• [ ] Add Earthly? Not sure if this is needed in the first place.
• [ ] Customize build-script.sh to generate binaries/executables for selective OSes
• [ ] Option to generate private projects - Shield badges and need the project to be public. It would be great to have an option to generate private projects using go-template!

:trophy: Acknowledgements

The main inspiration behind this template was TezRomacH's python-package-template — which I've greatly enjoyed using at one point of time.

The lack of any similar templates for Go was a large part of why I decided to Go ahead and make one myself. And of course, huge appreciation for Cookiecutter, without which such a flexible template would not be possible.

:2nd_place_medal: Similar Projects

Other similar project(s) that you might want to check out;

• cookiecutter-golang
• go-template-edge
• go-cli

P.S. If you know of any project similar to go-template (that isn't listed here), let me know and I'll be happy to list it ;)

Forks of go-template are welcome as well - given they have significant changes compared to upstream!

P.P.S. The emoji for this section fits well :p

:shield: License

This project is licensed under the terms of the MIT license. See LICENSE for more details.

Issues

Dump stderr logs in project `tmp` directory

Projects generated using go-template dump stderr messages in a text file in the /tmp directory. The reasoning behind this was that stderr output distracts users when everything is working, and with this setup, if there's a crash users can head over to the file in the /tmp directory to take a look at the logs.

https://github.com/notsatan/go-template/blob/0aef0d9e1aa750820ba873895a2a5d56e60adcf0/%7B%7B%20cookiecutter.project_name.strip()%20%7D%7D/Makefile#L15

But, there can be several scenarios where running Makefile commands might result in messages being printed to stderr — even if there are no failures — for example, warning messages. In such cases, users might not even be aware of the warning messages unless they keep checking the log file in /tmp (which is something that I doubt most people do).

Projects generated using go-template allow for a local tmp directory inside the project directory.

https://github.com/notsatan/go-template/blob/0aef0d9e1aa750820ba873895a2a5d56e60adcf0/%7B%7B%20cookiecutter.project_name.strip()%20%7D%7D/.gitignore#L5-L6

Though, at the moment, this tmp directory is not being automatically created through the post-gen hook (maybe this needs to change as well).

This issue simply suggests altering the existing behaviour to dump stderr logs generated by Makefile commands in the project local tmp directory instead of the global /tmp directory.

Releases

v1.0.0 2022-07-07 14:44:15

Stable Release

The first actual release for go-template — the project seems to be pretty stable right now and includes a ton of features out of the box — way too many to list here. Refer to the (current) project README for a complete list of features.