Skip to content

README.md

Latest commit

 

History

History
422 lines (297 loc) · 15.7 KB

README.md

File metadata and controls

422 lines (297 loc) · 15.7 KB
Raw

🚀  go-template

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


Release Go Version License


CI / CD    Build Last Commit      Quality    Coverage
Security    Scorecard Security      Community    Contributors Sponsor


Project Navigation

📦 Installation 🧪 Examples & Tests 📚 Documentation
🤝 Contributing 🛠️ Code Standards ⚡ Benchmarks
🤖 AI Usage ⚖️ License 👥 Maintainers

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



🚀 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"

git clone https://github.com/bsv-blockchain/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

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:

# 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

    • bsv-blockchain/go-template → yourorg/yourproject
    • go-template → yourproject
    • bsv-blockchain → yourorg

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

  3. 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. 🚀



┌──────────────────────────────────────────────────────────────────────────────────────────┐
│                                                                                          │
│                GO-TEMPLATE – YOUR README STARTS RIGHT AFTER THIS BANNER                  │
│                                                                                          │
└──────────────────────────────────────────────────────────────────────────────────────────┘
                                         ⬇ ⬇ ⬇


📦 Installation

go-template requires a supported release of Go.

go get -u github.com/bsv-blockchain/go-template

📚 Documentation

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.


Development Build Commands

Get the MAGE-X build tool for development:

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

View all build commands

magex help
Repository Features

This repository includes 25+ built-in features covering CI/CD, security, code quality, developer experience, and community tooling.

View the full Repository Features list →

Library Deployment

This project uses goreleaser for streamlined binary and library deployment to GitHub. To get started, install it via:

brew install goreleaser

The release process is defined in the .goreleaser.yml configuration file.

Then create and push a new Git tag using:

magex version:bump push=true bump=patch branch=master

This process ensures consistent, repeatable releases with properly versioned artifacts and citation metadata.

Pre-commit Hooks

Set up the Go-Pre-commit System to run the same formatting, linting, and tests defined in AGENTS.md before every commit:

go install github.com/mrz1836/go-pre-commit/cmd/go-pre-commit@latest
go-pre-commit install

The system is configured via modular env files in .github/env/ and provides 17x faster execution than traditional Python-based pre-commit hooks. See the complete documentation for details.

GitHub Workflows

All workflows are driven by modular configuration in .github/env/ — no YAML editing required.

View all workflows and the control center →

Updating Dependencies

To update all dependencies (Go modules, linters, and related tools), run:

magex deps:update

This command ensures all dependencies are brought up to date in a single step, including Go modules and any tools managed by MAGE-X. It is the recommended way to keep your development environment and CI in sync with the latest versions.


🧪 Examples & Tests

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

Run all tests (fast):

magex test

Run all tests with race detector (slower):

magex test:race

⚡ Benchmarks

Run the Go benchmarks:

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 Usage & Assistant Guidelines

Read the AI Usage & Assistant Guidelines for details on how AI is used in this project and how to interact with the AI assistants.


👥 Maintainers

MrZ
MrZ

🤝 Contributing

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

How can I help?

All kinds of contributions are welcome 🙌! The most basic way to show your support is to star 🌟 the project, or to raise issues 💬.

Stars


📝 License

License