Skip to content

Commit a5422a5

Browse files
pdylanrossclaude
pdylanross
and
claude
authored
doc: consolidate claude skills and add gh cli workflow (#2)
* test(e2e): add e2e stress test suite with minikube framework Implement end-to-end testing infrastructure including a Ginkgo-based test framework, workload scheduler, OCI image generator, and minikube setup scripts with Kustomize manifests for deploying barnacle, redis, and a local registry. Fixes bugs found in disk management and cache configuration during e2e validation. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * doc: consolidate claude skills into single code-standards skill and add gh cli workflow Replaces individual skill files with a unified code-standards skill containing all references. Adds comprehensive GitHub CLI documentation to the development workflow covering PR creation, CI checks, squash merging, and auto-merge. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent b4e0c37 commit a5422a5

53 files changed

Lines changed: 4026 additions & 181 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.claude/skills/code-standards/SKILL.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
name: code-standards
3+
description: Project code standards covering context usage, DI, workflow, errors, testing, API design, and Swagger docs. Always load when working with code in this repo.
4+
---
5+
6+
# Barnacle Code Standards
7+
8+
This project follows consistent patterns for Go development. Load the relevant reference documents below based on the area you're working in.
9+
10+
## References
11+
12+
| Reference | Load when... |
13+
|---|---|
14+
| [context-standards](references/context-standards.md) | Working with `context.Context` parameters or propagation |
15+
| [dependency-injection](references/dependency-injection.md) | Adding, modifying, or wiring dependencies via `internal/dependencies` |
16+
| [development-workflow](references/development-workflow.md) | Creating branches, commits, or PRs |
17+
| [environment-dependencies](references/environment-dependencies.md) | Adding dev tools or updating `make tools` |
18+
| [error-handling](references/error-handling.md) | Handling errors, defining sentinel errors, or returning HTTP errors |
19+
| [api-swagger-support](references/api-swagger-support.md) | Adding or updating Swagger/OpenAPI annotations |
20+
| [swagger-annotation-patterns](references/swagger-annotation-patterns.md) | Writing handler-level swagger comment blocks |
21+
| [swagger-model-documentation](references/swagger-model-documentation.md) | Documenting DTOs with struct tags, enums, or generics for swagger |
22+
| [internal-api-standards](references/internal-api-standards.md) | Building internal management API endpoints or DTOs |
23+
| [unit-testing-patterns](references/unit-testing-patterns.md) | Writing or modifying unit tests |

.claude/skills/api-swagger-support/SKILL.md renamed to .claude/skills/code-standards/references/api-swagger-support.md

Lines changed: 3 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,3 @@
1-
---
2-
name: api-swagger-support
3-
description: Guide for generating Swagger/OpenAPI documentation from Go code using swag and serving it via gin-swagger. Use when adding API documentation annotations to handlers, creating or updating Swagger comments, configuring swagger UI routes, running swag init/fmt, or troubleshooting documentation generation.
4-
---
5-
61
# API Swagger Support (swag + gin-swagger)
72

83
This project uses [swag](https://github.com/swaggo/swag) to generate Swagger 2.0 documentation from Go annotations, and [gin-swagger](https://github.com/swaggo/gin-swagger) to serve the interactive Swagger UI.
@@ -237,7 +232,7 @@ type Event struct {
237232
// time.Time auto-maps, but you can be explicit:
238233
CreatedAt time.Time `json:"createdAt" swaggertype:"string" format:"date-time"`
239234
240-
// Custom type → primitive
235+
// Custom type -> primitive
241236
Status AppStatus `json:"status" swaggertype:"string" enums:"running,stopped"`
242237
243238
// Map types
@@ -359,8 +354,8 @@ When adding swagger annotations to this codebase:
359354
360355
## Detailed References
361356
362-
- See [references/annotation-patterns.md](references/annotation-patterns.md) for complete annotation examples matching this project's patterns
363-
- See [references/model-documentation.md](references/model-documentation.md) for struct tag patterns, enums, composition, and generics
357+
- See [swagger-annotation-patterns.md](swagger-annotation-patterns.md) for complete annotation examples matching this project's patterns
358+
- See [swagger-model-documentation.md](swagger-model-documentation.md) for struct tag patterns, enums, composition, and generics
364359

365360
## External Resources
366361

.claude/skills/context-standards/SKILL.md renamed to .claude/skills/code-standards/references/context-standards.md

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,4 @@
1-
---
2-
name: context-standards
3-
description: Code standards whenever working with golang's `context.Context` type
4-
---
1+
# Context Standards
52

63
When working with golang's `context.Context` type, there are a few code standards that should be followed.
74
* Always check for cancellation, especially before doing expensive work.
@@ -11,5 +8,5 @@ When working with golang's `context.Context` type, there are a few code standard
118
* NEVER pass nil context.
129
* context.WithValue should only be used for carrying request-scoped, immutable data across API boundaries and between processes (e.g., security credentials, tracing IDs, or an authenticated user's details).
1310
* To avoid key collisions when using WithValue, define a custom, unexported type for your context keys, often an empty struct, rather than using basic types like string or int.
14-
* Do not use Context to pass optional function parameters; use regular function arguments for operational data.
11+
* Do not use Context to pass optional function parameters; use regular function arguments for operational data.
1512
* Avoid storing large data in the context. Use dedicated function parameters or structs for large data payload

.claude/skills/dependency-injection/SKILL.md renamed to .claude/skills/code-standards/references/dependency-injection.md

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,4 @@
1-
---
2-
name: dependency-injection
3-
description: Dependency injection patterns and practices for this project
4-
---
1+
# Dependency Injection
52

63
## Overview
74

@@ -221,4 +218,4 @@ if err != nil {
221218
return err
222219
}
223220
deps.Logger().Info("starting")
224-
```
221+
```

‎.claude/skills/code-standards/references/development-workflow.md‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
# Development Workflow
2+
3+
## Branch Naming Conventions
4+
5+
When starting work, create a branch from `main` using the appropriate prefix:
6+
7+
* `feat/<short-name>` - For new features (e.g., `feat/blob-replication`)
8+
* `bug/<description>` - For bug fixes (e.g., `bug/redis-connection-timeout`)
9+
* `doc/<description>` - For documentation changes (e.g., `doc/api-examples`)
10+
11+
## Development Workflow
12+
13+
1. **Create branch** from `main` with the appropriate prefix
14+
2. **Do the work** - implement the feature, fix, or documentation
15+
3. **Commit and push** - commit changes with descriptive messages, push to remote
16+
4. **Create PR** - open a pull request targeting `main`
17+
5. **Wait for CI** - ensure all pipelines pass
18+
6. **Get review** - wait for code review approval
19+
7. **Squash merge** - merge to `main` using squash merge
20+
21+
## Commit Message Style
22+
23+
Follow conventional commits where appropriate:
24+
* `feat:` - New feature
25+
* `fix:` - Bug fix
26+
* `doc:` or `docs:` - Documentation
27+
* `refactor:` - Code refactoring
28+
* `test:` - Adding or updating tests
29+
* `chore:` - Maintenance tasks
30+
31+
## GitHub CLI (`gh`) Reference
32+
33+
This project uses the `gh` CLI for all GitHub interactions. Authentication is handled via `gh auth login` (already configured for this repo).
34+
35+
### Creating a Branch and Pushing
36+
37+
```bash
38+
# Start from an up-to-date main
39+
git checkout main
40+
git pull origin main
41+
git checkout -b feat/<short-name>
42+
43+
# Stage and commit changes
44+
git add <files>
45+
git commit -m "feat: description of changes"
46+
47+
# Push and set upstream tracking (-u only needed on first push)
48+
git push -u origin feat/<short-name>
49+
```
50+
51+
### Creating a Pull Request
52+
53+
Use `gh pr create` to open a PR from the current branch:
54+
55+
```bash
56+
# Basic PR creation (will prompt for title and body if omitted)
57+
gh pr create --base main --title "feat: description" --body "Summary of changes"
58+
59+
# Use commit messages to auto-fill title and body
60+
gh pr create --base main --fill
61+
62+
# Use first commit for title, all commits for body
63+
gh pr create --base main --fill-first --fill-verbose
64+
65+
# Create a draft PR
66+
gh pr create --base main --title "feat: WIP description" --draft
67+
68+
# Use a heredoc for multi-line body
69+
gh pr create --base main --title "feat: description" --body "$(cat <<'EOF'
70+
## Summary
71+
- Change 1
72+
- Change 2
73+
74+
## Test Plan
75+
- [ ] Unit tests pass
76+
- [ ] E2E tests pass
77+
EOF
78+
)"
79+
```
80+
81+
### Checking PR Status
82+
83+
```bash
84+
# View the current branch's PR details
85+
gh pr view
86+
87+
# Check CI status for the current branch's PR
88+
gh pr checks
89+
90+
# Watch CI checks until they complete (polls every 10s)
91+
gh pr checks --watch
92+
93+
# Watch with a custom interval (seconds)
94+
gh pr checks --watch --interval 30
95+
96+
# Only show required checks
97+
gh pr checks --required
98+
99+
# List your open PRs
100+
gh pr list --author "@me"
101+
```
102+
103+
### Merging a Pull Request
104+
105+
Always use **squash merge** for this project:
106+
107+
```bash
108+
# Squash merge the current branch's PR and delete the branch
109+
gh pr merge --squash --delete-branch
110+
111+
# Squash merge with a custom commit message
112+
gh pr merge --squash --delete-branch \
113+
--subject "feat: description (#123)" \
114+
--body "Detailed description of the squashed changes"
115+
116+
# Enable auto-merge (merges automatically once CI passes and review is approved)
117+
gh pr merge --squash --delete-branch --auto
118+
119+
# Merge a specific PR by number
120+
gh pr merge 123 --squash --delete-branch
121+
```
122+
123+
### Full Workflow Example
124+
125+
```bash
126+
# 1. Create branch
127+
git checkout main && git pull origin main
128+
git checkout -b feat/blob-ttl
129+
130+
# 2. Do the work, commit
131+
git add internal/registry/cache/disk/cache.go
132+
git commit -m "feat: add TTL support for disk blob cache"
133+
134+
# 3. Push
135+
git push -u origin feat/blob-ttl
136+
137+
# 4. Create PR
138+
gh pr create --base main \
139+
--title "feat: add TTL support for disk blob cache" \
140+
--body "Adds configurable TTL eviction to the disk-based blob cache."
141+
142+
# 5. Wait for CI (watch checks in terminal)
143+
gh pr checks --watch
144+
145+
# 6. After approval, squash merge and clean up
146+
gh pr merge --squash --delete-branch
147+
148+
# 7. Return to main
149+
git checkout main && git pull origin main
150+
```
151+
152+
### Auto-Merge Workflow
153+
154+
When CI is still running or review is pending, enable auto-merge so the PR merges as soon as all requirements are met:
155+
156+
```bash
157+
# Create PR and immediately enable auto-merge
158+
gh pr create --base main \
159+
--title "feat: description" \
160+
--body "Summary of changes"
161+
162+
gh pr merge --squash --delete-branch --auto
163+
```
164+
165+
To disable auto-merge if plans change:
166+
167+
```bash
168+
gh pr merge --disable-auto
169+
```

.claude/skills/environment-dependencies/SKILL.md renamed to .claude/skills/code-standards/references/environment-dependencies.md

Lines changed: 8 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,8 @@
1-
---
2-
name: environment-dependencies
3-
description: Standards for managing development environment tools and keeping the Makefile tools recipe in sync
4-
---
1+
# Environment Dependencies
52

6-
## Environment Dependencies
3+
This covers the management of external development tools required to build, test, and develop the Barnacle project. All required tools must be documented here and installed via `make tools`.
74

8-
This skill covers the management of external development tools required to build, test, and develop the Barnacle project. All required tools must be documented here and installed via `make tools`.
9-
10-
### Required Tools
5+
## Required Tools
116

127
The following tools are required for development and are installed by `make tools`:
138

@@ -17,7 +12,7 @@ The following tools are required for development and are installed by `make tool
1712
| `goimports` | Code formatting with import organization | `go install golang.org/x/tools/cmd/goimports@latest` |
1813
| `golangci-lint` | Linting and static analysis (v2 required) | `go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest` |
1914

20-
### Adding a New Tool
15+
## Adding a New Tool
2116

2217
When adding a new development tool dependency:
2318

@@ -45,9 +40,9 @@ tools:
4540
@echo "All tools installed successfully"
4641
```
4742

48-
Then update this skill document to include mockgen in the Required Tools table.
43+
Then update this document to include mockgen in the Required Tools table.
4944

50-
### First-Time Setup
45+
## First-Time Setup
5146

5247
New developers should run:
5348

@@ -57,12 +52,12 @@ make tools
5752

5853
This installs all required development tools. Run this command again if tools are updated or new tools are added.
5954

60-
### Version Pinning
55+
## Version Pinning
6156

6257
Currently, tools are installed at `@latest`. If version pinning becomes necessary for reproducibility, update the install commands to use specific versions:
6358

6459
```makefile
6560
go install github.com/swaggo/swag/cmd/swag@v1.16.6
6661
```
6762

68-
Document any pinned versions and the reason for pinning in this file.
63+
Document any pinned versions and the reason for pinning in this file.

.claude/skills/error-handling/SKILL.md renamed to .claude/skills/code-standards/references/error-handling.md

Lines changed: 4 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,6 @@
1-
---
2-
name: error-handling
3-
description: Skill for handling errors in code
4-
---
1+
# Error Handling
52

6-
## Error Handling
3+
## Sentinel Errors
74
- **NEVER use inline `fmt.Errorf()` calls in function returns** - Always use global error variables
85
- Define global error variables at package level using `errors.New()`:
96
```go
@@ -22,7 +19,7 @@ description: Skill for handling errors in code
2219
- Always wrap underlying errors with `%w` to preserve the error chain
2320
- Include relevant context (filenames, paths, etc.) between the sentinel error and wrapped error
2421

25-
### HTTP API Errors
22+
## HTTP API Errors
2623
- **ALWAYS use `internal/tk/httptk` error factories for HTTP API errors** - These conform to the OCI distribution specification
2724
- Use pre-defined factory methods instead of constructing errors manually:
2825
```go
@@ -50,4 +47,4 @@ description: Skill for handling errors in code
5047

5148
// BAD:
5249
c.Error(httptk.ErrManifestUnknown(nil)) // Linter will warn about unchecked error
53-
```
50+
```

0 commit comments

Comments
 (0)