template

README

🚀 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 Makefile
  make test, make lint, make 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 + 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, CODEOWNERS, 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 make 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) Personalize the template in one command

make install-template owner=my_org repo=my-lib

What does that command do?

1. Finds & replaces names

   • bsv-blockchain/go-template → my_org/my-lib
   • go-template → my-lib
   • bsv-blockchain → my_org

2. Cleans up after itself

   • Deletes the temporary install file .make/temp.mk
   • Removes its own include .make/temp.mk line from the root Makefile

3. House-keeping

   • Remove the default social-share image so you can drop in your own

That’s it—open a diff, make sure you're happy, commit, and push. 🎉

3) Touch up metadata

Edit the highlighted files so they match your project:

• AGENTS.md
  • Update the project name, description, and any other relevant details at the beginning of the file
• 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 make tag version=0.1.0 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

• API Reference – Dive into the godocs at pkg.go.dev/github.com/bsv-blockchain/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 that's strictly for tests.

Repository Features

• Continuous Integration on Autopilot with GitHub Actions – every push is built, tested, and reported in minutes.
• Pull‑Request Flow That Merges Itself thanks to auto‑merge and hands‑free Dependabot auto‑merge.
• One‑Command Builds powered by battle‑tested Make targets for linting, testing, releases, and more.
• First‑Class Dependency Management using native Go Modules.
• Uniform Code Style via gofumpt plus zero‑noise linting with golangci‑lint.
• Confidence‑Boosting Tests with testify, the Go race detector, crystal‑clear HTML coverage snapshots, and automatic uploads to Codecov.
• Hands‑Free Releases delivered by GoReleaser whenever you create a new Tag.
• Relentless Dependency & Vulnerability Scans via Dependabot, Nancy, and govulncheck.
• Security Posture by Default with CodeQL, OpenSSF Scorecard, and secret‑leak detection via gitleaks.
• Automatic Syndication to pkg.go.dev on every release for instant godoc visibility.
• Polished Community Experience using rich templates for Issues & PRs.
• All the Right Meta Files (LICENSE, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SUPPORT.md, SECURITY.md) pre‑filled and ready.
• Code Ownership clarified through a CODEOWNERS file, keeping reviews fast and focused.
• Zero‑Noise Dev Environments with tuned editor settings (.editorconfig) plus curated ignore files for VS Code, Docker, and Git.
• Label Sync Magic: your repo labels stay in lock‑step with .github/labels.yml.
• Friendly First PR Workflow – newcomers get a warm welcome thanks to a dedicated workflow.
• Standards‑Compliant Docs adhering to the standard‑readme spec.
• Instant Cloud Workspaces via Gitpod – spin up a fully configured dev environment with automatic linting and tests.
• Out‑of‑the‑Box VS Code Happiness with a preconfigured Go workspace and .vscode folder with all the right settings.
• Optional Release Broadcasts to your community via Slack, Discord, or Twitter – plug in your webhook.
• AI Compliance Playbook – machine‑readable guidelines (AGENTS.md, CLAUDE.md, .cursorrules, sweep.yaml) keep ChatGPT, Claude, Cursor & Sweep aligned with your repo’s rules.
• Pre-commit Hooks for Consistency powered by pre-commit and the .pre-commit-config.yaml file—run the same formatting, linting, and tests before every commit, just like CI.
• Automated Hook Updates keep the .pre-commit-config.yaml current via a weekly workflow.
• DevContainers for Instant Onboarding – Launch a ready-to-code environment in seconds with VS Code DevContainers and the included .devcontainer.json config.

Repository File Glossary

This glossary describes each tracked file in the repository and notes if it is required for GitHub or another external service.

File Path	Description	Service
.cursorrules	Rules for Cursor AI integrations	Cursor
.devcontainer.json	VS Code dev or GitHub container configuration	VS Code & GitHub
.dockerignore	Paths ignored by Docker builds	Docker
.editorconfig	Editor configuration defaults	Editor
.gitattributes	Git attributes and export settings	Git
.github/.env.shared	Shared environment variables for GitHub Actions	GitHub Actions
.github/AGENTS.md	Contribution rules and guidelines	GitHub
.github/CLAUDE.md	Claude agent instructions	Claude
.github/CODEOWNERS	Code ownership declarations for GitHub	GitHub
.github/CODE_OF_CONDUCT.md	Community behavior standards	GitHub
.github/CODE_STANDARDS.md	Coding style guide	GitHub
.github/CONTRIBUTING.md	How to contribute to the project	GitHub
.github/FUNDING.yml	Funding links displayed by GitHub	GitHub
.github/ISSUE_TEMPLATE/bug_report.yml	Issue template for bug reports	GitHub
.github/ISSUE_TEMPLATE/feature_request.yml	Issue template for feature requests	GitHub
.github/ISSUE_TEMPLATE/question.yml	Issue template for questions	GitHub
.github/SECURITY.md	Security policy	GitHub
.github/SUPPORT.md	Support guidelines	GitHub
.github/actions/warm-cache/action.yml	Action to warm GitHub Actions cache	GitHub Actions
.github/dependabot.yml	Dependabot configuration	GitHub
.github/labels.yml	Repository label definitions	GitHub
.github/pull_request_template.md	Pull request description template	GitHub
.github/sweep.yaml	Sweep AI configuration	Sweep AI
.github/workflows/auto-merge-on-approval.yml	Workflow for automatic merges	GitHub Actions
.github/workflows/codeql-analysis.yml	CodeQL security analysis workflow	GitHub Actions
.github/workflows/dependabot-auto-merge.yml	Auto merge Dependabot PRs	GitHub Actions
.github/workflows/fortress.yml	Fortress security & testing workflow	GitHub Actions
.github/workflows/pull-request-management.yml	Pull request triage workflow	GitHub Actions
.github/workflows/scorecard.yml	OpenSSF Scorecard workflow	GitHub Actions
.github/workflows/stale.yml	Close stale issues and PRs	GitHub Actions
.github/workflows/sync-labels.yml	Sync repository labels	GitHub Actions
.github/workflows/update-python-dependencies.yml	Update Python dependencies for pre-commit hooks	GitHub Actions
.github/workflows/update-pre-commit-hooks.yml	Automatically update pre-commit hooks	GitHub Actions
.gitignore	Files and directories Git should ignore	Git
.gitpod.yml	Gitpod workspace configuration	Gitpod
.golangci.json	GolangCI-Lint configuration	GolangCI-Lint
.goreleaser.yml	GoReleaser configuration for release automation	GoReleaser
.make/common.mk	Shared make tasks	Make
.make/go.mk	Go-specific make tasks	Make
.make/temp.mk	Temporary makefile for internal use	Make
.pre-commit-config.yaml	Pre-commit hooks configuration	Pre-commit
.vscode/extensions.json	Recommended VS Code extensions	VS Code
.vscode/launch.json	VS Code debugging configuration	VS Code
.vscode/settings.json	VS Code workspace settings	VS Code
.vscode/tasks.json	VS Code tasks configuration	VS Code
Dockerfile	Docker image build instructions	Docker
LICENSE	Project license	Yours!
Makefile	Build and lint automation	Make
README.md	Project overview and usage	Yours!
codecov.yml	Codecov upload configuration	Codecov
examples/example.go	Example usage of the library	None
go.mod	Go module definition	Go
go.sum	Dependency checksums generated by Go	Go
template.go	Main package source code	Yours!
template_benchmark_test.go	Go benchmark tests	Go test
template_example_test.go	Example tests for documentation	Go test
template_fuzz_test.go	Go fuzz tests	Go test
template_test.go	Unit tests	Go test

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.

To generate a snapshot (non-versioned) release for testing purposes, run:

make release-snap

Then create and push a new Git tag using:

make tag version=x.y.z

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

Makefile Commands

View all makefile commands

make help

List of all current commands:

bench                 ## Run all benchmarks in the Go application
build-go              ## Build the Go application (locally)
citation              ## Update version in CITATION.cff (use version=X.Y.Z)
clean-mods            ## Remove all the Go mod cache
coverage              ## Show test coverage
diff                  ## Show git diff and fail if uncommitted changes exist
fumpt                 ## Run fumpt to format Go code
generate              ## Run go generate in the base of the repo
godocs                ## Trigger GoDocs tag sync
govulncheck-install   ## Install govulncheck (pass VERSION= to override)
govulncheck           ## Scan for vulnerabilities
help                  ## Display this help message
install-go            ## Install using go install with specific version
install-releaser      ## Install GoReleaser
install-stdlib        ## Install the Go standard library for the host platform
install-template      ## Kick-start a fresh copy of go-template (run once!)
install               ## Install the application binary
lint-version          ## Show the golangci-lint version
lint                  ## Run the golangci-lint application (install if not found)
loc                   ## Total lines of code table
mod-download          ## Download Go module dependencies
mod-tidy              ## Clean up go.mod and go.sum
pre-build             ## Pre-build all packages to warm cache
release-snap          ## Build snapshot binaries
release-test          ## Run release dry-run (no publish)
release               ## Run production release (requires github_token)
tag-remove            ## Remove local and remote tag (use version=X.Y.Z)
tag-update            ## Force-update tag to current commit (use version=X.Y.Z)
tag                   ## Create and push a new tag (use version=X.Y.Z)
test-ci-no-race       ## CI test suite without race detector
test-ci               ## CI test runs tests with race detection and coverage (no lint - handled separately)
test-cover-race       ## Runs unit tests with race detector and outputs coverage
test-cover            ## Unit tests with coverage (no race)
test-fuzz             ## Run fuzz tests only (no unit tests)
test-no-lint          ## Run only tests (no lint)
test-parallel         ## Run tests in parallel (faster for large repos)
test-race             ## Unit tests with race detector (no coverage)
test-short            ## Run tests excluding integration tests (no lint)
test                  ## Default testing uses lint + unit tests (fast)
uninstall             ## Uninstall the Go binary
update-linter         ## Upgrade golangci-lint (macOS only)
update-releaser       ## Reinstall GoReleaser
update                ## Update dependencies
vet-parallel          ## Run go vet in parallel (faster for large repos)
vet                   ## Run go vet only on your module packages

GitHub Workflows

🎛️ The Workflow Control Center

All GitHub Actions workflows in this repository are powered by a single configuration file: .env.shared – your one-stop shop for tweaking CI/CD behavior without touching a single YAML file! 🎯

This magical file controls everything from:

• 🚀 Go version matrix (test on multiple versions or just one)
• 🏃 Runner selection (Ubuntu or macOS, your wallet decides)
• 🔬 Feature toggles (coverage, fuzzing, linting, race detection)
• 🛡️ Security tool versions (gitleaks, nancy, govulncheck)
• 🤖 Auto-merge behaviors (how aggressive should the bots be?)
• 🏷️ PR management rules (size labels, auto-assignment, welcome messages)

Pro tip: Want to disable code coverage? Just flip ENABLE_CODE_COVERAGE=false in .env.shared and push. No YAML archaeology required!

Workflow Name	Description
auto-merge-on-approval.yml	Automatically merges PRs after approval and all required checks, following strict rules.
codeql-analysis.yml	Analyzes code for security vulnerabilities using GitHub CodeQL.
dependabot-auto-merge.yml	Automatically merges Dependabot PRs that meet all requirements.
fortress.yml	Runs the GoFortress security and testing workflow, including linting, testing, releasing, and vulnerability checks.
pull-request-management.yml	Labels PRs by branch prefix, assigns a default user if none is assigned, and welcomes new contributors with a comment.
scorecard.yml	Runs OpenSSF Scorecard to assess supply chain security.
stale.yml	Warns about (and optionally closes) inactive issues and PRs on a schedule or manual trigger.
sync-labels.yml	Keeps GitHub labels in sync with the declarative manifest at .github/labels.yml.
update-python-dependencies.yml	Updates Python dependencies for pre-commit hooks in the repository.
update-pre-commit-hooks.yml	Automatically update versions for pre-commit hooks

Updating Dependencies

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

make update

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

Pre-commit Hooks

Set up the optional pre-commit hooks to run the same formatting, linting, and tests defined in AGENTS.md before every commit:

pip install pre-commit
pre-commit install

The hooks are configured in .pre-commit-config.yaml and mirror the CI pipeline.

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

make test

Run all tests with race detector (slower):

make test-race

⚡ Benchmarks

Run the Go benchmarks:

make 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

Siggi

🤝 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 💬. You can also support this project by becoming a sponsor on GitHub 👏

📝 License

Documentation

Overview

Package template provides a robust starter template for building new Go libraries.

This package implements foundational patterns and utilities for Go library development and is designed to help developers quickly scaffold, test, and maintain secure, idiomatic Go code.

Key features include: - Built-in support for code quality, testing, and CI/CD workflows - Example functions and best-practice patterns for Go libraries

The package is structured for modularity and ease of extension, following Go community conventions. It relies on the Go standard library and popular tools for testing and linting.

Usage examples:

msg := template.Greet("Alice")
fmt.Println(msg) // Output: Hello Alice

Important notes: - Assumes Go modules are used for dependency management - No external configuration is required for basic usage - Designed for use as a starting point for new Go projects

This package is part of the go-template project and is intended to be copied or forked for new Go library development.

Index

• func Greet(firstname string) string

Examples

• Greet

Functions

func Greet

func Greet(firstname string) string

Greet returns a greeting message for the given first name.

This function performs the following steps: - Formats a greeting string using the provided first name.

Parameters: - firstname: The first name to include in the greeting message.

Returns: - A string containing the greeting message.

Side Effects: - None.

Notes: - Assumes firstname is a non-empty string; no validation is performed. - This function is standalone and not part of a larger workflow.

Example

ExampleGreet demonstrates the usage of the Greet function.

msg := template.Greet("Alice")
fmt.Println(msg)

Output:

Hello Alice