{"id":20619103,"url":"https://github.com/cep21/gotemplate","last_synced_at":"2025-04-15T11:50:18.461Z","repository":{"id":57551840,"uuid":"201829929","full_name":"cep21/gotemplate","owner":"cep21","description":"Minimal repository template for well constructed Go libraries.","archived":false,"fork":false,"pushed_at":"2019-09-19T22:51:18.000Z","size":42,"stargazers_count":33,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-28T19:44:45.801Z","etag":null,"topics":["go","golang","template-project"],"latest_commit_sha":null,"homepage":"https://github.com/cep21/gotemplate/generate","language":"Makefile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cep21.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-08-12T00:22:10.000Z","updated_at":"2025-02-28T03:02:06.000Z","dependencies_parsed_at":"2022-09-20T12:52:10.755Z","dependency_job_id":null,"html_url":"https://github.com/cep21/gotemplate","commit_stats":null,"previous_names":[],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cep21%2Fgotemplate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cep21%2Fgotemplate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cep21%2Fgotemplate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cep21%2Fgotemplate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cep21","download_url":"https://codeload.github.com/cep21/gotemplate/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249067144,"owners_count":21207392,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["go","golang","template-project"],"created_at":"2024-11-16T12:10:39.425Z","updated_at":"2025-04-15T11:50:18.435Z","avatar_url":"https://github.com/cep21.png","language":"Makefile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gotemplate\n[![CircleCI](https://circleci.com/gh/cep21/gotemplate.svg)](https://circleci.com/gh/cep21/gotemplate)\n[![GoDoc](https://godoc.org/github.com/cep21/gotemplate?status.svg)](https://godoc.org/github.com/cep21/gotemplate)\n[![codecov](https://codecov.io/gh/cep21/gotemplate/branch/master/graph/badge.svg)](https://codecov.io/gh/cep21/gotemplate)\n\nA short one sentence description of your code, such as Gotemplate is a minimal template repository for well constructed\nGitHub go libraries.\n\nExplain why (not how) someone would want to use this code.  This should be a bit of a sales pitch.  Use gotemplate to\nspin up a new Go library on GitHub, without making it a direct fork.  It sets you up with the minimal parts you'll want\nto ensure your code starts and stays at a high quality.  You can read more about template repositories\n[from GitHub](https://github.blog/2019-06-06-generate-new-repositories-with-repository-templates/).\n\nThis setup includes:\n* Continuous testing with [CircleCI](https://circleci.com/) on multiple go versions.\n* Static analysis checking with [golangci-lint](https://github.com/golangci/golangci-lint).\n* Setup [go modules](https://github.com/golang/go/wiki/Modules).\n* Widely usable source license Apache 2.0\n* [godoc](https://godoc.org) source code documentation\n* Code coverage reporting with [codecov](https://codecov.io)\n* [Makefile](https://en.wikipedia.org/wiki/Makefile) helper for formatting, building, and running your code.\n* Testable [examples](https://blog.golang.org/examples).\n* Basic [README](https://en.wikipedia.org/wiki/README) file with good starting sections.\n\n# Usage\n\nInclude usage examples.  These can often be links or direct copies from your\n[example test file](./gotemplate_example_test.go).\n\n\u003c!--\n```go\n    func ExampleRemoveMe() {\n    \tfmt.Println(gotemplate.RemoveMe(\"hello\", \"world\"))\n    }\n```\n--\u003e\nTo use gotemplate:\n1. Visit the generation URL for gotemplate at https://github.com/cep21/gotemplate/generate and create your repository.\n2. Sign in with GitHub for [CircleCI](https://circleci.com) and [codecov](https://codecov.io).  Afterwards, enable each\nfor your repository.  Direct links to enable look something like this for [codecov](https://codecov.io/gh/cep21/+) and\n[CircleCI](https://circleci.com/add-projects/gh/cep21), but for your user name.\n3. Rename cep21/gotemplate to your repository.  There is a makefile helper this, which expects an OWNER\n and REPO parameter.  For example, if you were to setup the github repository github.com/example/athing you would run\n `make setup_repo OWNER=example REPO=athing`.\n4. Take out the parts of the README that don't make sense.  Keep the sections you want.\n5. Push your repository and watch it build.\n\n# Design Rational\n\nTalk about why you wrote this code the way you did.  A lot of this may focus on what you decided **not** to do.\nFor the things you did do, explain why it's important.  This may serve as a mini-FAQ while your project is small.\nMove this out to something more heavy weight like [GitHub Pages](https://pages.github.com) if your project gets very\ncomplex.\n\n## License file\n\nA [license](./LICENSE.txt) file is mandatory for open source projects.  Which you use is up to you. Most companies I've\nseen appreciate [Apache 2.0](https://tldrlegal.com/license/apache-license-2.0-(apache-2.0)) for the patent clauses.\nAnother reasonable choice is [MIT](https://tldrlegal.com/license/mit-license).\n\n## README\n\nA [readme](./README.md) file is the first thing people see when they visit your code repository and should convince\nsomeone to want to use your code and be a launching pad to other tasks.  When your project is a huge hit, you can move\nthis somewhere else, but for small projects a README should be enough for all information you need.\n\n## Makefile\n\nA [Makefile](./Makefile) is a concise way to communicate what common terms like \"linting\" or \"testing\" mean exactly. \nFor example, testing isn't just \"go test\", it's \"go test on all files with the -race detector\". Similarly, linting isn't\njust \"running go vet\", it may be \"running golangci-lint with some flags\".  Makefile targets should be common software\nterms like \"build\" or \"test\" that contain specific commands for what that term means.\n\n## Continuous testing\n\n[CircleCI](./.circleci) allows you to run checks on requests and commits to make sure your code stays working.\nAnother popular choice is [TravisCI](https://travis-ci.org).  Travis is a fine choice: I just prefer CircleCI.  I've\ntalked about why on a previous post\n[The 13 Things That Make a Good Build System](https://www.signalfx.com/blog/the-13-things-that-make-a-good-build-system/).\nAn important bonus for me is that CircleCI is free for private git repositories, which lets me test out code before I'm\nready to make it public.\n\nI purposly keep commands inside CI systems simple, like `make XYZ`, instead of embedding the command, like\n`go test -v -race ./...`, because I feel depending upon a common standard like a Makefile makes it easier to later\nswitch CI systems.  The more complex your CI system's commands become, the more difficult it is to debug the system\nlocally or migrate to another CI provider.\n\n## Static analysis\n\nAutomatic detection of software bugs is very powerful and can help push new code above a minimum bar of quality.\nThe best for Go right now is [Golangci-lint](https://github.com/golangci/golangci-lint).  By combining the output of\nmany linters, reusing source code parsing between linters, using semantic versioning, and configuration from a yml file\nit allows easy, precise, reproducible, and comprehensive static analysis.\n\nThe linters configured in [.golangci.yml](./.golangci.yml) seem to be reasonable defaults.  Feel free to add or remove\nthem as you want.\n\n## Testable examples\n\nI really like [testable examples](./gotemplate_example_test.go) as code documentation that verifies itself as correct (unlike actual documentation blocks\nwhich are never compiled).  Testable examples also integrate well with godoc and most IDE help dialogs.\n\n## doc.go\n\nPackage level documentation is useful for godoc users: which is the standard documentation format for Go.  Package level\ndocumentation is generally placed in a separate [doc.go](./doc.go) file. Write this documentation assuming people are\nalready sold on using your code and just want broader context on how to use the library correctly.  Focus less on\nexplicit usage and more on overall API correctness.\n\n## tools.go\n\nA [tools.go](./tools.go) file is a nice way to lock down versions of go binaries that you later download with `go install`.\nSome more information about this approach on [GitHub](https://github.com/golang/go/issues/25922) and the primary\nwiki page for [go modules](https://github.com/golang/go/wiki/Modules#how-can-i-track-tool-dependencies-for-a-module).\n\n## Visible code coverage\n\nTest code coverage of some amount can communicate a commitment to having working code. Both\n[codecov](https://codecov.io) and [coveralls](https://docs.coveralls.io/go)\nare fine.  I've defaulted to codecov since it integrates well with CircleCI and did not require a separate step of\nuploading a token to your CI's environment: making it easier for new developers to just get started.\n\nCodecov usually recommends downloading and executing a shell command from an unversioned URL.  To mitigate issues\naround this, I instead download directly from\n[a SHA1 version](https://raw.githubusercontent.com/codecov/codecov-bash/1044b7a243e0ea0c05ed43c2acd8b7bb7cef340c/codecov).\n\nIf you're generating artifacts like coverage profiles, you'll want to add them to your [.gitignore](./.gitignore) file as well.\n\n## Go modules\n\n[Modules](./go.mod) are the now standard way to manage dependencies of Go code.  The CI process runs both `go mod download` and\n`go mod verify` to check your dependencies.\nThe build process uses `-mod=readonly` to ensure your CI checks the `go.mod` file for missing dependencies.\n\nThe [go.sum](./go.sum) file is checked into the repository to verify your downloaded dependencies continue to match and\naren't changed from under you.\n\n# Contributing\n\nTell people how they can contribute.  Start with something simple and create a `CONTRIBUTING.md` file if you really\nneed it.\n\nContributions welcome!  Submit a pull request on github and make sure your code passes `make lint test`.  For\nlarge changes, I strongly recommend [creating an issue](https://github.com/cep21/gotemplate/issues) on GitHub first to\nconfirm your change will be accepted before writing a lot of code.  GitHub issues are also recommended, at your discretion,\nfor smaller changes or questions.\n\n# License\n\nThis library is licensed under the Apache 2.0 License.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcep21%2Fgotemplate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcep21%2Fgotemplate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcep21%2Fgotemplate/lists"}