<div align="center" markdown="1">

# Go Project Template

[![Go](https://img.shields.io/badge/Go-1.24+-00ADD8?logo=go&logoColor=white)](https://go.dev/dl/)
[![npm version](https://img.shields.io/npm/v/@mai0313/go_template?logo=npm&style=flat-square&color=CB3837)](https://www.npmjs.com/package/@mai0313/go_template)
[![npm downloads](https://img.shields.io/npm/dt/@mai0313/go_template?logo=npm&style=flat-square)](https://www.npmjs.com/package/@mai0313/go_template)
[![tests](https://github.com/Mai0313/go_template/actions/workflows/test.yml/badge.svg)](.github/workflows/test.yml)
[![code-quality](https://github.com/Mai0313/go_template/actions/workflows/code-quality-check.yml/badge.svg)](https://github.com/Mai0313/go_template/actions/workflows/code-quality-check.yml)
[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)
[![license](https://img.shields.io/badge/License-MIT-green.svg?labelColor=gray)](https://github.com/Mai0313/go_template/tree/master?tab=License-1-ov-file)
[![PRs](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/Mai0313/go_template/pulls)
[![contributors](https://img.shields.io/github/contributors/Mai0313/go_template.svg)](https://github.com/Mai0313/go_template/graphs/contributors)

</div>

🚀 A production‑ready Golang project template to bootstrap new Go services and CLIs quickly. It ships with a pragmatic layout, Makefile, Docker builds, and a complete CI/CD suite.

Click [Use this template](../../generate) to start a new repository from this scaffold.

Other Languages: [English](README.md) | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md)

## ✨ Highlights

- Makefile tasks: build, test, cross‑compile, format, dead‑code scan
- Version embedding via `-ldflags` (version, build time, git commit)
- Example CLI under `cmd/go_template` with `--version`
- Unit tests with coverage artifact in CI
- Docker: multi‑stage image build with cache and minimal runtime
- GitHub Actions: test, lint (golangci‑lint), image build+push, release drafter, labels, secret/code scanning

## 🚀 Quick Start

Prerequisites:

- Go 1.24+
- Docker (optional, for container builds)

Local setup:

```bash
make build            # build binaries into ./build/
make run              # build and run the main command
make test             # run unit tests with coverage
make fmt              # format code (go fmt ./...)
make build-all        # cross‑compile common OS/ARCH targets
```

Run the example CLI:

```bash
./build/go_template --version
```

## Using as a Template

**IMPORTANT**: This is a template, not a library. You must rename `go_template` to your project name.

### Quick Setup

1. Click **Use this template** to create your repository
2. Clone your new repository
3. Run the rename script or follow manual steps below

### Manual Rename Steps

**Required changes** (replace `{your_project}` with your actual project name):

1. **Go Module**:

    - Update `go.mod`: `module go_template` → `module {your_project}`
    - Rename `cmd/go_template/` → `cmd/{your_project}/`
    - Update imports in `cmd/{your_project}/main.go`
    - Update `Makefile` LDFLAGS (lines 17-19) and `BIN_NAME` (line 23)

2. **CLI Wrappers** (if using npm/PyPI distribution):

    - Node.js: Update `cli/nodejs/package.json` and `cli/nodejs/bin/start.js`
    - Python: Update `cli/python/pyproject.toml` and rename `cli/python/src/go_template/`

3. **Docker**:

    - Update `docker/Dockerfile` labels and binary paths
    - Update `.devcontainer/Dockerfile` labels

4. **Documentation**:

    - Update badge URLs in `README.md`, `README.zh-CN.md`, `README.zh-TW.md`
    - Update `.github/CODEOWNERS`

**Verification**:

```bash
make clean && make build
./build/{your_project} --version
grep -r "go_template" --exclude-dir=.git --exclude-dir=build .
```

For detailed instructions, see [.github/copilot-instructions.md](.github/copilot-instructions.md).

## Project Structure

```text
cmd/go_template/     # Main CLI entrypoint
core/version/        # Version utilities and tests
build/               # Build outputs (git‑ignored)
docker/Dockerfile    # Multi‑stage image build
```

## Docker

```bash
# Build & run image locally
docker build -t your/image:dev -f docker/Dockerfile .
docker run --rm -it your/image:dev
```

## CI/CD (GitHub Actions)

- tests: `.github/workflows/test.yml`
- quality: `.github/workflows/code-quality-check.yml`
- release package: `.github/workflows/build_release.yml`
- docker image: `.github/workflows/build_image.yml`
- release drafter: `.github/workflows/release_drafter.yml`
- labels & semantics: `.github/workflows/auto_labeler.yml`, `semantic-pull-request.yml`
- security: `.github/workflows/code_scan.yml` (gitleaks, trivy, codeql)

## Contribution

- Run `make fmt && make test` before pushing
- Keep PRs focused and small; include tests
- Use Conventional Commit messages
