From bf30fb344d8a85960b391b4f622c3855288f0926 Mon Sep 17 00:00:00 2001 From: karolswdev Date: Sat, 30 Aug 2025 18:29:43 -0600 Subject: [PATCH 1/4] chore(ci): align Codecov config with coverage.txt\n\n- Use go test -coverprofile=coverage.txt\n- Upload artifact and Codecov input as coverage.txt\n\nNo Jira ticket; routine CI maintenance change. --- .github/workflows/ci.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 6d37a9f..f8eb992 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -31,7 +31,7 @@ jobs: version: latest args: --timeout=5m - name: Test - run: go test ./... -race -coverprofile=coverage.out + run: go test ./... -race -coverprofile=coverage.txt - name: Govulncheck uses: golang/govulncheck-action@v1 with: @@ -42,12 +42,12 @@ jobs: uses: actions/upload-artifact@v4 with: name: coverage - path: coverage.out + path: coverage.txt - name: Upload coverage to Codecov if: success() || failure() uses: codecov/codecov-action@v4 with: - files: coverage.out + files: coverage.txt flags: unittests fail_ci_if_error: false env: From 1684d31b1b9b9bd4659be1295bc3ef6f966042c1 Mon Sep 17 00:00:00 2001 From: karolswdev Date: Sat, 30 Aug 2025 18:36:25 -0600 Subject: [PATCH 2/4] chore(ci): use codecov/codecov-action@v5 with token/slug\n\n- Switch from v4 to v5\n- Pass token via input and set slug\n- Rely on autodiscovery for coverage.txt --- .github/workflows/ci.yml | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index f8eb992..9ce0421 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -45,10 +45,7 @@ jobs: path: coverage.txt - name: Upload coverage to Codecov if: success() || failure() - uses: codecov/codecov-action@v4 + uses: codecov/codecov-action@v5 with: - files: coverage.txt - flags: unittests - fail_ci_if_error: false - env: - CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} + token: ${{ secrets.CODECOV_TOKEN }} + slug: karolswdev/ticketr From 37b34e6c33abc7c92135b35f28291ba9ed7a37a7 Mon Sep 17 00:00:00 2001 From: karolswdev Date: Sat, 30 Aug 2025 18:46:43 -0600 Subject: [PATCH 3/4] chore(ci): ensure coverage.txt is generated at repo root\n\n- Move flags before packages\n- Add -covermode=atomic and -coverpkg=./...\n- Stabilize single coverage.txt for artifact/Codecov --- .github/workflows/ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 9ce0421..d7b1c9a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -31,7 +31,7 @@ jobs: version: latest args: --timeout=5m - name: Test - run: go test ./... -race -coverprofile=coverage.txt + run: go test -race -covermode=atomic -coverpkg=./... -coverprofile=coverage.txt ./... - name: Govulncheck uses: golang/govulncheck-action@v1 with: From 68eeb535cce436842f0122df2bd5ff628243f3f9 Mon Sep 17 00:00:00 2001 From: karolswdev Date: Sat, 30 Aug 2025 18:55:17 -0600 Subject: [PATCH 4/4] docs: OSS-ready docs sweep\n\n- Align Go version to 1.24+ across docs\n- Fix CI/CD examples; add composite action + CLI variants\n- Add docs/CI.md with Codecov v5 guidance\n- Standardize branching to GitHub Flow\n- Replace gosec with govulncheck; remove aspirational links --- CONTRIBUTING.md | 2 +- README.md | 1 + docs/CI.md | 75 +++++++++++++++++++++++++++++++++++++++++ docs/DEVELOPMENT.md | 39 ++++++++++----------- docs/GETTING_STARTED.md | 37 ++++++++++++++++---- 5 files changed, 124 insertions(+), 30 deletions(-) create mode 100644 docs/CI.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 65ebdd6..20bc956 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -96,7 +96,7 @@ for retries := 0; retries < maxRetries; retries++ { cd ticketr ``` -2. **Install Go 1.22 or later:** +2. **Install Go 1.24 or later:** Follow the instructions at https://go.dev/doc/install 3. **Install dependencies:** diff --git a/README.md b/README.md index e16d3dd..11425fb 100644 --- a/README.md +++ b/README.md @@ -106,6 +106,7 @@ Format: Use `# TICKET:` headings in Markdown files. - Architecture: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) - Webhooks: [docs/WEBHOOKS.md](docs/WEBHOOKS.md) - Development: [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) +- CI & Coverage: [docs/CI.md](docs/CI.md) - CLI Reference: [docs/CLI.md](docs/CLI.md) - Examples: [examples/](examples/) - Rich custom fields example: [examples/tickets_with_custom_fields.md](examples/tickets_with_custom_fields.md) diff --git a/docs/CI.md b/docs/CI.md new file mode 100644 index 0000000..6159838 --- /dev/null +++ b/docs/CI.md @@ -0,0 +1,75 @@ +# Continuous Integration and Coverage + +This guide shows how to run Ticketr’s CI and report coverage with Codecov. + +## GitHub Actions + +Minimal workflow that vets, lints, tests with coverage, and uploads to Codecov: + +```yaml +name: CI + +on: + push: + branches: [ main ] + pull_request: + branches: [ main ] + +jobs: + build-test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-go@v5 + with: + go-version-file: go.mod + + - name: Vet + run: go vet ./... + + - name: Lint + uses: golangci/golangci-lint-action@v4 + with: + version: latest + args: --timeout=5m + + - name: Test + run: go test -race -covermode=atomic -coverpkg=./... -coverprofile=coverage.txt ./... + + - name: Upload coverage artifact + if: always() + uses: actions/upload-artifact@v4 + with: + name: coverage + path: coverage.txt + + - name: Upload coverage reports to Codecov + if: success() || failure() + uses: codecov/codecov-action@v5 + with: + token: ${{ secrets.CODECOV_TOKEN }} + slug: karolswdev/ticketr +``` + +Notes: +- `-covermode=atomic` pairs well with `-race`. +- `-coverpkg=./...` ensures a single `coverage.txt` at the repo root. +- Codecov v5 autodiscovers `coverage.txt`; explicit `files:` is optional. + +## Local Checks + +Run the same steps locally: + +```bash +go vet ./... +golangci-lint run +go test -race -covermode=atomic -coverpkg=./... -coverprofile=coverage.txt ./... +``` + +Open an HTML coverage report: + +```bash +go tool cover -html=coverage.txt -o coverage.html +``` + diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index ac0eb1d..c9f349d 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -6,17 +6,15 @@ This guide provides comprehensive instructions for setting up your development e ### Required Software -- **Go 1.22 or later**: [Download Go](https://go.dev/dl/) +- **Go 1.24 or later**: [Download Go](https://go.dev/dl/) - **Git**: [Download Git](https://git-scm.com/downloads) - **Make** (optional): For simplified command execution - **Docker** (optional): For containerized development ### Recommended Tools -- **VS Code** with Go extension -- **GoLand** IDE -- **golangci-lint**: For code quality checks -- **ko**: For building container images +- **VS Code** with Go extension or GoLand IDE +- **golangci-lint**: Code quality checks (matches CI) ## Setting Up Your Development Environment @@ -117,6 +115,7 @@ go test -timeout 30s ./... ```bash # Run tests with race detector go test -race ./... +``` ## Local Lint and Security Checks @@ -146,15 +145,12 @@ This repository enforces a Go toolchain via `go.mod`: toolchain go1.24.4 ``` -Most tools (including `go` itself and GitHub Actions `setup-go`) will automatically install/use this version when `go-version-file: go.mod` is configured. If you want to override locally for a single shell, you can use: +Most tools (including `go` itself and GitHub Actions `setup-go`) automatically install/use this version when `go-version-file: go.mod` is configured. If you want to override locally for a single shell, you can use: ```bash GOTOOLCHAIN=go1.24.4 ``` -# Note: This makes tests slower but catches concurrency issues -``` - ### Benchmark Tests ```bash @@ -206,15 +202,14 @@ func TestTicketService_ProcessTickets(t *testing.T) { ### Branch Strategy -We follow a Git Flow-inspired branching model: +We follow GitHub Flow: ``` -main - Production-ready code -├── develop - Integration branch for features -├── feat/* - Feature branches -├── fix/* - Bug fix branches -├── docs/* - Documentation updates -└── refactor/* - Code refactoring +main - Production-ready code +feat/* - Feature branches +fix/* - Bug fix branches +docs/* - Documentation updates +refactor/* - Code refactoring ``` ### Creating a Feature Branch @@ -280,7 +275,7 @@ git commit -m "refactor(services): Extract validation logic to separate package" ### Code Review Process 1. **Create Pull Request** - - Target the `develop` branch + - Target the `main` branch - Fill out the PR template - Link related issues @@ -323,8 +318,8 @@ golangci-lint run # Run go vet go vet ./... -# Check for security issues -gosec ./... +# Check for known vulnerabilities +govulncheck ./... ``` ### Editor Configuration @@ -484,10 +479,10 @@ Our CI pipeline runs on every push and pull request: 1. **Lint**: Code style and quality checks 2. **Test**: Unit and integration tests 3. **Build**: Cross-platform binary compilation -4. **Coverage**: Code coverage reporting +4. **Coverage**: Code coverage reporting (Codecov) 5. **Security**: Vulnerability scanning -### Running CI Locally +### Running CI Locally (optional) ```bash # Install act (GitHub Actions locally) @@ -499,7 +494,7 @@ curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash act push # Run specific job -act -j test +act -j build-test ``` ## Release Process diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md index cd17e0c..8ae0419 100644 --- a/docs/GETTING_STARTED.md +++ b/docs/GETTING_STARTED.md @@ -15,7 +15,7 @@ Welcome to Ticketr! This guide will walk you through setting up and using Ticket Before you begin, ensure you have: -1. **Go 1.22+** installed (for building from source) +1. **Go 1.24+** installed (for building from source) 2. **JIRA Account** with API access enabled 3. **JIRA API Token** (not your password!) - Generate at: https://id.atlassian.com/manage-profile/security/api-tokens @@ -238,16 +238,40 @@ Use emojis for visual status: ### CI/CD Integration -Automate ticket creation in GitHub Actions: +Automate ticket sync in GitHub Actions. + +Option A — Install CLI and run: +```yaml +jobs: + ticketr: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-go@v5 + with: + go-version-file: go.mod + - name: Install ticketr + run: go install github.com/karolswdev/ticketr/cmd/ticketr@latest + - name: Push tickets + env: + JIRA_URL: ${{ secrets.JIRA_URL }} + JIRA_EMAIL: ${{ secrets.JIRA_EMAIL }} + JIRA_API_KEY: ${{ secrets.JIRA_API_KEY }} + JIRA_PROJECT_KEY: PROJ + run: ticketr push stories/backlog.md +``` + +Option B — Use the composite action from this repo: ```yaml - name: Push tickets to JIRA - uses: karolswdev/ticketr-action@v1 + uses: karolswdev/ticketr/.github/actions/ticketr-sync@main # Pin to a tag in production with: - file: stories/backlog.md jira-url: ${{ secrets.JIRA_URL }} jira-email: ${{ secrets.JIRA_EMAIL }} jira-api-key: ${{ secrets.JIRA_API_KEY }} jira-project-key: PROJ + command: push + file-path: stories/backlog.md ``` ### Real-time Sync @@ -323,11 +347,10 @@ ticketr pull --strategy=remote-wins ## Getting Help -- 📚 [Full Documentation](https://github.com/karolswdev/ticketr/wiki) - 💬 [GitHub Discussions](https://github.com/karolswdev/ticketr/discussions) - 🐛 [Report Issues](https://github.com/karolswdev/ticketr/issues) -- 📧 [Contact Support](mailto:support@ticketr.dev) +- 📚 Project docs live in the `docs/` folder of this repo --- -Happy ticket management! 🎫 \ No newline at end of file +Happy ticket management! 🎫