🚀 go-template

From Zero to Go Hero: Pre-wired Template for Modern Libraries

CI / CD	Quality & Security	Docs & Meta	Community

🗂️ Table of Contents

• What's Inside
• Installation
• Documentation
• Examples & Tests
• Benchmarks
• Code Standards
• AI Compliance
• Maintainers
• Contributing
• License

🧩 What's Inside

go-template is a plug-and-play scaffold that lets you skip the boilerplate and jump straight to building your Go library. Clone it, rename a few placeholders, and you instantly inherit a production-grade setup:

• 📚 Go Best Practices & Examples Includes idiomatic Go patterns, table-driven tests, benchmarks, example functions, and fuzz tests—demonstrating how to write robust, maintainable, and production-grade Go code.

• ⚡ Zero-config CI/CD GitHub Actions run tests, upload coverage, and enforce linting on every push—so you never forget to run the checks.

• 🛠️ One-command via MAGE-X magex test, magex lint, magex bench, and more—common tasks stay muscle-memory simple.

• 🚢 Automated Releases GoReleaser cuts signed, versioned artifacts the moment you push a tag—shipping new versions becomes a 10-second ritual.

• 🛡️ Security & Supply-chain Guardrails Dependabot, Nancy, govulncheck, CodeQL, OpenSSF Scorecard and gitleaks give early warnings before bad things reach production.

• 🎨 Style & Quality Enforcement golangci-lint with 50+ linters and gofumpt keeps the codebase clean and idiomatic - no bikeshedding required.

• 🤖 AI-Friendly Policies AGENTS.md, CLAUDE.md, cursorrules, and sweep.yaml ensure ChatGPT, Claude, Cursor & Sweep follow the same house rules.

• 🌍 Community-Ready Meta [Issue/PR templates](.github/ISSUETEMPLATE), CODEOWNERS, CITATION, label sync, and a welcome bot to show contributors exactly how to get involved._

🚀 Quick Wins

• Clone → Tag → Release: Go from idea to a published version in under five minutes.
• Works Everywhere: macOS, Linux, Windows (maybe lol), ARM64 – fully reproducible builds.
• Battery-Included Examples: ready-to-run demos, benchmarks, fuzz and race tests.
• Flexible, Not Fragile: swap or remove any piece without breaking the whole.

Tip: Run magex help right after cloning to see every command the template unlocks.

🛠 Template Kick-Off Guide (3 Easy Steps)

(delete this section once your project is initialized)

1) Clone or "Use this template"

bash git clone https://github.com/mrz1836/go-template.git my-lib && cd my-lib

... or click Use this template on GitHub and create a new repo.

2) Install MAGE-X build tool and run the installation script

```bash go install github.com/mrz1836/mage-x/cmd/magex@latest

Run the install script to customize the project for your organization

magex installTemplate owner=yourorg repo=yourproject ```

Example: ```bash

For GitHub user "acme" creating a project called "awesome-api"

magex installTemplate owner=acme repo=awesome-api ```

What does that command do?

1. Finds & replaces names across 70+ files

* `mrz1836/go-template` → `yourorg/yourproject`
* `go-template` → `yourproject`
* `mrz1836` → `yourorg`

1. Cleans up template artifacts

* Removes the default social-share image so you can add your own
* Updates module paths in `go.mod`
* Fixes all GitHub badges and links

1. Provides helpful feedback

* Shows exactly which files were modified
* Gives you next steps to review and commit changes

3) Touch up metadata

Edit the highlighted files so they match your project:

• LICENSE
  • Update the year and your name or organization
• README.md
  • Remove the "remove-this-section" block in this file
  • Modify the "About" section to describe your library
• .github/SECURITY.md
  • Update the security policy to match your project's needs
• .github/FUNDING.yml
  • If you want to accept funding, add your funding links here
• .goreleaser.yml
  • Modify settings for Slack, Discord, Twitter, or Reddit if you want to announce releases
• CODEOWNERS
  • Adjust rules for code ownership if needed

Give it a spin!

Push your initial commit and run magex version:bump push=true bump=minor and the CI/CD pipeline will take it from there. 🚀

text ┌──────────────────────────────────────────────────────────────────────────────────────────┐ │ │ │ MR. Z'S GO-TEMPLATE – YOUR README STARTS RIGHT AFTER THIS BANNER │ │ │ └──────────────────────────────────────────────────────────────────────────────────────────┘ ⬇ ⬇ ⬇

📦 Installation

go-template requires a supported release of Go. shell script go get -u github.com/mrz1836/go-template

Get the MAGE-X build tool for development: shell script go install github.com/mrz1836/mage-x/cmd/magex@latest

📚 Documentation

• API Reference – Dive into the godocs at pkg.go.dev/github.com/mrz1836/go-template
• Usage Examples – Browse practical patterns either the examples directory or view the example functions
• Benchmarks – Check the latest numbers in the benchmark results
• Test Suite – Review both the unit tests and fuzz tests (powered by testify)

Good to know: go-template ships with zero runtime dependencies. The only external package we use is testify and magefile — and that's strictly for tests and dev.

🧪 Examples & Tests

All unit tests and examples run via GitHub Actions and use Go version 1.24.x. View the configuration file.

Run all tests (fast):

bash script magex test

Run all tests with race detector (slower): bash script magex test:race

⚡ Benchmarks

Run the Go benchmarks:

bash script magex bench

Benchmark Results

| Benchmark | Iterations | ns/op | B/op | allocs/op | |-------------------------------------|------------|------:|-----:|----------:| | Greet | 21,179,739 | 56.59 | 40 | 2 |

These benchmarks reflect fast, allocation-free lookups for most retrieval functions, ensuring optimal performance in production environments. Performance benchmarks for the core functions in this library, executed on an Apple M1 Max (ARM64).

🛠️ Code Standards

Read more about this Go project's code standards.

🤖 AI Compliance

This project documents expectations for AI assistants using a few dedicated files:

• AGENTS.md — canonical rules for coding style, workflows, and pull requests used by Codex.
• CLAUDE.md — quick checklist for the Claude agent.
• .cursorrules — machine-readable subset of the policies for Cursor and similar tools.
• sweep.yaml — rules for Sweep, a tool for code review and pull request management.

Edit AGENTS.md first when adjusting these policies, and keep the other files in sync within the same pull request.

👥 Maintainers

| | |:-----------------------------------------------------------------------------------------------------------:| | MrZ |

🤝 Contributing

View the contributing guidelines and please follow the code of conduct.

How can I help?

All kinds of contributions are welcome :raisedhands:! The most basic way to show your support is to star :star2: the project, or to raise issues :speechballoon:. You can also support this project by becoming a sponsor on GitHub :clap: or by making a bitcoin donation to ensure this journey continues indefinitely! :rocket:

📝 License