Skip to content

Latest commit

 

History

History
399 lines (307 loc) · 21.9 KB

README.md

File metadata and controls

399 lines (307 loc) · 21.9 KB
Raw

go-template

A gif displaying go-template in action

Build status No Dependencies MIT License Pre-Commit Enabled Go v1.19+ Makefile Included

A bleeding-edge Go project generator for your next project 😉

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 ;)

💥 Features

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

Development

  • Supports Go v1.19, v1.20 and v1.21
  • 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!

🔬 Setup Instructions

Installation

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

pip install -U cookiecutter

Once you have cookiecutter installed, move over to the directory where you want to generate your project and run 
cookiecutter gh:notsatan/go-template

Alternatively, you can achieve the same results with the command

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
private_project n Yes or No (y or n). Inquires if the project repository generated will be publicly accessible, or private. Why is this needed?
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 😉

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

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 :)

🎯 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

⁉️ 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

Why do I need to inform if the generated project will be public?

As of now, the only change(s) being made based on this are all restricted to the README file of generated projects. This is required as some badges used in the README require the project to be accessible by shields.io — the service behind these badges!

For private projects, these badges will either be removed or modified, to prevent cases where badges break down for private repositories!

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

^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

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.

✔️ 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! (Accomplished via #52)

🏆 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.

🥈 Similar Projects

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

🛡️ License

MIT License

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