Skip to content

Commit 15af923

Browse files
debidongdebidong
committed
docs: add README and upgrade CI/CD pipeline
Add comprehensive README with installation, quick start, command reference, output format docs, and development guide. Upgrade CI/CD to match flashduty-mcp-server: - Multi-OS test matrix (ubuntu, windows, macos) - Separate lint workflow with golangci-lint v2.11 - CodeQL security scanning - GoReleaser with signed build provenance attestations - Draft releases with uname-compatible archive naming - Comprehensive Makefile with fmt, gci, lint, test, tools targets
1 parent 14577a7 commit 15af923

7 files changed

Lines changed: 540 additions & 47 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 23 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,33 @@
1-
name: CI
1+
name: Build and Test
22

3-
on:
4-
push:
5-
branches: [main]
6-
pull_request:
7-
branches: [main]
3+
on: [push, pull_request]
4+
5+
permissions:
6+
contents: read
87

98
jobs:
109
build:
11-
runs-on: ubuntu-latest
10+
strategy:
11+
fail-fast: false
12+
matrix:
13+
os: [ubuntu-latest, windows-latest, macos-latest]
14+
15+
runs-on: ${{ matrix.os }}
16+
1217
steps:
13-
- uses: actions/checkout@v4
18+
- name: Check out code
19+
uses: actions/checkout@v4
1420

15-
- uses: actions/setup-go@v5
21+
- name: Set up Go
22+
uses: actions/setup-go@v5
1623
with:
17-
go-version: "1.24"
24+
go-version-file: "go.mod"
1825

19-
- name: Build
20-
run: go build ./...
26+
- name: Download dependencies
27+
run: go mod download
2128

22-
- name: Vet
23-
run: go vet ./...
29+
- name: Run unit tests
30+
run: go test -race ./...
2431

25-
- name: Test
26-
run: go test -race -cover ./...
32+
- name: Build
33+
run: go build -v ./cmd/flashduty

‎.github/workflows/code-scanning.yml‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
name: "CodeQL"
2+
3+
on: [push, pull_request, workflow_dispatch]
4+
5+
concurrency:
6+
group: ${{ github.workflow }}-${{ github.ref }}
7+
cancel-in-progress: true
8+
9+
jobs:
10+
analyze:
11+
name: Analyze (${{ matrix.language }})
12+
runs-on: ubuntu-22.04
13+
permissions:
14+
actions: read
15+
contents: read
16+
packages: read
17+
security-events: write
18+
strategy:
19+
fail-fast: false
20+
matrix:
21+
include:
22+
- language: actions
23+
category: /language:actions
24+
build-mode: none
25+
- language: go
26+
category: /language:go
27+
build-mode: autobuild
28+
steps:
29+
- name: Checkout repository
30+
uses: actions/checkout@v4
31+
32+
- name: Initialize CodeQL
33+
uses: github/codeql-action/init@v3
34+
with:
35+
languages: ${{ matrix.language }}
36+
build-mode: ${{ matrix.build-mode }}
37+
38+
- name: Setup Go
39+
uses: actions/setup-go@v5
40+
if: matrix.language == 'go'
41+
with:
42+
go-version-file: "go.mod"
43+
44+
- name: Autobuild
45+
uses: github/codeql-action/autobuild@v3
46+
47+
- name: Perform CodeQL Analysis
48+
uses: github/codeql-action/analyze@v3
49+
with:
50+
category: ${{ matrix.category }}

‎.github/workflows/lint.yml‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
name: golangci-lint
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
pull_request:
8+
9+
permissions:
10+
contents: read
11+
12+
jobs:
13+
golangci:
14+
name: lint
15+
runs-on: ubuntu-latest
16+
steps:
17+
- uses: actions/checkout@v4
18+
- uses: actions/setup-go@v5
19+
with:
20+
go-version: stable
21+
- name: golangci-lint
22+
uses: golangci/golangci-lint-action@v8
23+
with:
24+
version: v2.11

‎.github/workflows/release.yml‎

Lines changed: 24 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
name: Release
1+
name: GoReleaser Release
22

33
on:
44
push:
@@ -7,22 +7,40 @@ on:
77

88
permissions:
99
contents: write
10+
id-token: write
11+
attestations: write
1012

1113
jobs:
1214
release:
1315
runs-on: ubuntu-latest
16+
1417
steps:
15-
- uses: actions/checkout@v4
18+
- name: Check out code
19+
uses: actions/checkout@v4
1620
with:
1721
fetch-depth: 0
1822

19-
- uses: actions/setup-go@v5
23+
- name: Set up Go
24+
uses: actions/setup-go@v5
2025
with:
21-
go-version: "1.24"
26+
go-version-file: "go.mod"
27+
28+
- name: Download dependencies
29+
run: go mod download
2230

23-
- uses: goreleaser/goreleaser-action@v6
31+
- name: Run GoReleaser
32+
uses: goreleaser/goreleaser-action@v6
2433
with:
25-
version: latest
34+
distribution: goreleaser
35+
version: "~> v2"
2636
args: release --clean
2737
env:
2838
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
39+
40+
- name: Generate signed build provenance attestations
41+
uses: actions/attest-build-provenance@v2
42+
with:
43+
subject-path: |
44+
dist/*.tar.gz
45+
dist/*.zip
46+
dist/*.txt

‎.goreleaser.yml‎

Lines changed: 24 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,45 @@
11
version: 2
2+
project_name: flashduty-cli
3+
before:
4+
hooks:
5+
- go mod tidy
6+
- go generate ./...
27

38
builds:
4-
- main: ./cmd/flashduty
5-
binary: flashduty
6-
env:
9+
- env:
710
- CGO_ENABLED=0
11+
ldflags:
12+
- -s -w -X main.version={{.Version}} -X main.commit={{.Commit}} -X main.date={{.Date}}
813
goos:
914
- linux
10-
- darwin
1115
- windows
16+
- darwin
1217
goarch:
1318
- amd64
1419
- arm64
15-
ldflags:
16-
- -s -w -X main.version={{.Version}} -X main.commit={{.ShortCommit}} -X main.date={{.Date}}
20+
main: ./cmd/flashduty
1721

1822
archives:
19-
- format: tar.gz
20-
name_template: "{{ .ProjectName }}_{{ .Os }}_{{ .Arch }}"
23+
- formats: tar.gz
24+
name_template: >-
25+
{{ .ProjectName }}_
26+
{{- title .Os }}_
27+
{{- if eq .Arch "amd64" }}x86_64
28+
{{- else if eq .Arch "386" }}i386
29+
{{- else }}{{ .Arch }}{{ end }}
30+
{{- if .Arm }}v{{ .Arm }}{{ end }}
2131
format_overrides:
2232
- goos: windows
23-
format: zip
33+
formats: zip
2434

2535
changelog:
2636
sort: asc
2737
filters:
2838
exclude:
2939
- "^docs:"
3040
- "^test:"
31-
- "^chore:"
41+
42+
release:
43+
draft: true
44+
prerelease: auto
45+
name_template: "Flashduty CLI {{.Version}}"

‎Makefile‎

Lines changed: 136 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,142 @@
1-
BINARY=flashduty
2-
VERSION=$(shell git describe --tags --always --dirty)
3-
COMMIT=$(shell git rev-parse --short HEAD)
4-
DATE=$(shell date -u +%Y-%m-%dT%H:%M:%SZ)
5-
LDFLAGS=-ldflags "-s -w -X main.version=$(VERSION) -X main.commit=$(COMMIT) -X main.date=$(DATE)"
1+
# Build configuration
2+
BINARY_NAME := flashduty
3+
BUILD_DIR := bin
4+
GOLANGCI_LINT_VERSION := v2.2.1
5+
GOLANGCI_LINT := $(BUILD_DIR)/golangci-lint
6+
GCI_VERSION := v0.13.5
7+
GCI := $(BUILD_DIR)/gci
68

7-
.PHONY: build check lint test clean
9+
# Go parameters
10+
GOCMD := go
11+
GOBUILD := $(GOCMD) build
12+
GOTEST := $(GOCMD) test
13+
GOFMT := gofmt
14+
MODULE := $(shell go list -m)
815

9-
build:
10-
go build $(LDFLAGS) -o bin/$(BINARY) ./cmd/flashduty
16+
# Build metadata
17+
VERSION := $(shell git describe --tags --always --dirty 2>/dev/null || echo "dev")
18+
COMMIT := $(shell git rev-parse --short HEAD 2>/dev/null || echo "none")
19+
DATE := $(shell date -u +%Y-%m-%dT%H:%M:%SZ)
20+
LDFLAGS := -ldflags "-s -w -X main.version=$(VERSION) -X main.commit=$(COMMIT) -X main.date=$(DATE)"
1121

12-
check: lint test build
22+
# Default target
23+
.PHONY: all
24+
all: check
1325

14-
lint:
15-
golangci-lint run ./...
26+
# ============================================================================
27+
# Development targets
28+
# ============================================================================
1629

17-
test:
18-
go test -race -cover ./...
30+
.PHONY: build
31+
build: ## Build the binary
32+
$(GOBUILD) -v $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME) ./cmd/flashduty
1933

20-
clean:
21-
rm -rf bin/
34+
.PHONY: run
35+
run: build ## Build and run the CLI
36+
./$(BUILD_DIR)/$(BINARY_NAME)
37+
38+
# ============================================================================
39+
# Quality assurance targets
40+
# ============================================================================
41+
42+
FMT_DIRS := cmd internal
43+
44+
.PHONY: fmt
45+
fmt: $(GCI) ## Format Go source code and sort imports
46+
$(GOFMT) -s -w $(FMT_DIRS)
47+
$(GCI) write --skip-generated -s standard -s default -s "prefix($(MODULE))" $(FMT_DIRS)
48+
49+
.PHONY: gci
50+
gci: $(GCI) ## Sort imports using gci
51+
$(GCI) write --skip-generated -s standard -s default -s "prefix($(MODULE))" $(FMT_DIRS)
52+
53+
.PHONY: lint
54+
lint: $(GOLANGCI_LINT) ## Run golangci-lint
55+
$(GOLANGCI_LINT) run
56+
57+
.PHONY: lint-fix
58+
lint-fix: $(GOLANGCI_LINT) ## Run golangci-lint with auto-fix
59+
$(GOLANGCI_LINT) run --fix
60+
61+
.PHONY: test
62+
test: ## Run unit tests
63+
$(GOTEST) -race ./...
64+
65+
.PHONY: test-v
66+
test-v: ## Run unit tests with verbose output
67+
$(GOTEST) -race -v ./...
68+
69+
.PHONY: test-cover
70+
test-cover: ## Run unit tests with coverage
71+
$(GOTEST) -race -cover ./...
72+
73+
# ============================================================================
74+
# Pre-push check (recommended before pushing)
75+
# ============================================================================
76+
77+
.PHONY: check
78+
check: fmt lint test build ## Run all checks (fmt, lint, test, build) - recommended before pushing
79+
80+
.PHONY: ci
81+
ci: check ## Alias for check
82+
83+
# ============================================================================
84+
# Dependency management
85+
# ============================================================================
86+
87+
.PHONY: deps
88+
deps: ## Download Go dependencies
89+
$(GOCMD) mod download
90+
91+
.PHONY: deps-tidy
92+
deps-tidy: ## Tidy Go modules
93+
$(GOCMD) mod tidy
94+
95+
.PHONY: deps-verify
96+
deps-verify: ## Verify Go dependencies
97+
$(GOCMD) mod verify
98+
99+
# ============================================================================
100+
# Tools installation
101+
# ============================================================================
102+
103+
$(BUILD_DIR):
104+
mkdir -p $(BUILD_DIR)
105+
106+
$(GOLANGCI_LINT): $(BUILD_DIR)
107+
@if [ ! -f "$(GOLANGCI_LINT)" ]; then \
108+
echo "Installing golangci-lint $(GOLANGCI_LINT_VERSION)..."; \
109+
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s $(GOLANGCI_LINT_VERSION); \
110+
fi
111+
112+
$(GCI): $(BUILD_DIR)
113+
@if [ ! -f "$(GCI)" ]; then \
114+
echo "Installing gci $(GCI_VERSION)..."; \
115+
GOBIN=$(CURDIR)/$(BUILD_DIR) $(GOCMD) install github.com/daixiang0/gci@$(GCI_VERSION); \
116+
fi
117+
118+
.PHONY: tools
119+
tools: $(GOLANGCI_LINT) $(GCI) ## Install required tools
120+
121+
# ============================================================================
122+
# Cleanup
123+
# ============================================================================
124+
125+
.PHONY: clean
126+
clean: ## Remove build artifacts
127+
rm -rf $(BUILD_DIR)
128+
129+
# ============================================================================
130+
# Help
131+
# ============================================================================
132+
133+
.PHONY: help
134+
help: ## Display this help message
135+
@echo "Available targets:"
136+
@echo ""
137+
@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf " \033[36m%-15s\033[0m %s\n", $$1, $$2}'
138+
@echo ""
139+
@echo "Quick start:"
140+
@echo " make check - Run all pre-push checks (recommended before pushing)"
141+
@echo " make lint - Run linter only"
142+
@echo " make test - Run unit tests only"

0 commit comments

Comments
 (0)