A short one sentence description of your code, such as Gotemplate is a minimal template repository for well constructed GitHub go libraries.
Explain why (not how) someone would want to use this code. This should be a bit of a sales pitch. Use gotemplate to spin up a new Go library on GitHub, without making it a direct fork. It sets you up with the minimal parts you'll want to ensure your code starts and stays at a high quality. You can read more about template repositories from GitHub.
This setup includes:
- Continuous testing with CircleCI on multiple go versions.
- Static analysis checking with golangci-lint.
- Setup go modules.
- Widely usable source license Apache 2.0
- godoc source code documentation
- Code coverage reporting with codecov
- Makefile helper for formatting, building, and running your code.
- Testable examples.
- Basic README file with good starting sections.
Include usage examples. These can often be links or direct copies from your example test file.
To use gotemplate:
- Visit the generation URL for gotemplate at https://github.com/cep21/gotemplate/generate and create your repository.
- Sign in with GitHub for CircleCI and codecov. Afterwards, enable each for your repository. Direct links to enable look something like this for codecov and CircleCI, but for your user name.
- Rename cep21/gotemplate to your repository. There is a makefile helper this, which expects an OWNER
and REPO parameter. For example, if you were to setup the github repository github.com/example/athing you would run
make setup_repo OWNER=example REPO=athing. - Take out the parts of the README that don't make sense. Keep the sections you want.
- Push your repository and watch it build.
Talk about why you wrote this code the way you did. A lot of this may focus on what you decided not to do. For the things you did do, explain why it's important. This may serve as a mini-FAQ while your project is small. Move this out to something more heavy weight like GitHub Pages if your project gets very complex.
A license file is mandatory for open source projects. Which you use is up to you. Most companies I've seen appreciate Apache 2.0 for the patent clauses. Another reasonable choice is MIT.
A readme file is the first thing people see when they visit your code repository and should convince someone to want to use your code and be a launching pad to other tasks. When your project is a huge hit, you can move this somewhere else, but for small projects a README should be enough for all information you need.
A Makefile is a concise way to communicate what common terms like "linting" or "testing" mean exactly. For example, testing isn't just "go test", it's "go test on all files with the -race detector". Similarly, linting isn't just "running go vet", it may be "running golangci-lint with some flags". Makefile targets should be common software terms like "build" or "test" that contain specific commands for what that term means.
CircleCI allows you to run checks on requests and commits to make sure your code stays working. Another popular choice is TravisCI. Travis is a fine choice: I just prefer CircleCI. I've talked about why on a previous post The 13 Things That Make a Good Build System. An important bonus for me is that CircleCI is free for private git repositories, which lets me test out code before I'm ready to make it public.
I purposly keep commands inside CI systems simple, like make XYZ, instead of embedding the command, like
go test -v -race ./..., because I feel depending upon a common standard like a Makefile makes it easier to later
switch CI systems. The more complex your CI system's commands become, the more difficult it is to debug the system
locally or migrate to another CI provider.
Automatic detection of software bugs is very powerful and can help push new code above a minimum bar of quality. The best for Go right now is Golangci-lint. By combining the output of many linters, reusing source code parsing between linters, using semantic versioning, and configuration from a yml file it allows easy, precise, reproducible, and comprehensive static analysis.
The linters configured in .golangci.yml seem to be reasonable defaults. Feel free to add or remove them as you want.
I really like testable examples as code documentation that verifies itself as correct (unlike actual documentation blocks which are never compiled). Testable examples also integrate well with godoc and most IDE help dialogs.
Package level documentation is useful for godoc users: which is the standard documentation format for Go. Package level documentation is generally placed in a separate doc.go file. Write this documentation assuming people are already sold on using your code and just want broader context on how to use the library correctly. Focus less on explicit usage and more on overall API correctness.
A tools.go file is a nice way to lock down versions of go binaries that you later download with go install.
Some more information about this approach on GitHub and the primary
wiki page for go modules.
Test code coverage of some amount can communicate a commitment to having working code. Both codecov and coveralls are fine. I've defaulted to codecov since it integrates well with CircleCI and did not require a separate step of uploading a token to your CI's environment: making it easier for new developers to just get started.
Codecov usually recommends downloading and executing a shell command from an unversioned URL. To mitigate issues around this, I instead download directly from a SHA1 version.
If you're generating artifacts like coverage profiles, you'll want to add them to your .gitignore file as well.
Modules are the now standard way to manage dependencies of Go code. The CI process runs both go mod download and
go mod verify to check your dependencies.
The build process uses -mod=readonly to ensure your CI checks the go.mod file for missing dependencies.
The go.sum file is checked into the repository to verify your downloaded dependencies continue to match and aren't changed from under you.
Tell people how they can contribute. Start with something simple and create a CONTRIBUTING.md file if you really
need it.
Contributions welcome! Submit a pull request on github and make sure your code passes make lint test. For
large changes, I strongly recommend creating an issue on GitHub first to
confirm your change will be accepted before writing a lot of code. GitHub issues are also recommended, at your discretion,
for smaller changes or questions.
This library is licensed under the Apache 2.0 License.