And you're good to go! Jump to the setup section directly for quick setup instructions ;)
This is a battries-included cookiecutter :cookie: template to get you started with the essentials you'll need for your next Go project ;)
.gitignore- you won't have to bother with trivialities
Makefile- run linters, check for codestyle, run tests and generate coverage reports - all with a single command
SECURITY.mdwill be generated automatically.
To start using the template, install the latest version of
Cookiecutter (make sure you have Python and
pip install -U cookiecutter
Once you have cookiecutter installed, move over to the directory where you want to generate your project and run
Alternatively, you can achieve the same results with the command
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 |
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. |
master | The stable/base branch. Used for build status badges and release-drafter (if you enable Github specific features) |
"" | Email to get in touch with project stakeholders.
SECURITY.md will be removed if empty. Why is this needed? |
github_specific_features | y | Yes or No (
n). Dictates if Github-specific features should be included in the project (issue templates, pipeline, etc). More Info |
use_codecov | y | Yes or No (
n). Decides if Codecov is to be used in the project or not. Checkout Setting up codecov |
use_precommit | y | Yes or No (
n). Decides if pre-commit configs should be included with the generated templates |
1.17 | The version of Go to use in the project. Can be either
MIT | The license you want to use in the generated project. One of
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
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
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
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 :)
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
Articles and resources which were of great help to me when making this template
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
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
CODE_OF_CONDUCT.mdwill 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!
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_pathshould be a path to a Github repository (does not matter if it exists). This would be used for
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_featuresfield), or to not use Codecov (through the
use_codecovfield) - 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
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.
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,
the following regex expression to validate module paths
This check is needed is to ensure the
will add the repository owner as a reviewer whenever dependabot raises a pull request
for a dependency update.
dependabotfor 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
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
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);
.golangci.yml- The generated file should be enough to give users (developers) a rough idea of configs.
The main inspiration behind this template was
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.
Other similar project(s) that you might want to check out;
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
This project is licensed under the terms of the
MIT license. See LICENSE
for more details.
Projects generated using
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.
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.
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
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.
Software DevGitHub Repository
best-practices makefile cookiecutter cookiecutter-template go codestyle template cookiecutter-golang formatters