Implement
Foundation for any code change in luthersystems/svc. Follow this loop for every change.
Workflow
1. Understand the Change
- Read CLAUDE.md for project conventions and domain glossary
- Read existing code in the target package before modifying
- Check if the package has existing tests (
*_test.go) to understand testing patterns
2. Create a Feature Branch
# Branch from main, use username/Description format
git checkout main && git pull
git checkout -b sam-at-luther/Short_description
3. Make Changes
- Follow existing code style in the package
- Add copyright header to new files:
// Copyright © <year> Luther Systems, Ltd. All right reserved. - If adding a new package, create it at the top level (flat package structure)
- Do NOT edit generated code in
oracle/testservice/gen/
4. Format & Lint
# Format
gofmt -w .
# Lint (matches CI — gosec enabled)
golangci-lint run
Fix any lint issues before proceeding. The gosec linter is enabled — pay attention to security findings.
5. Build
go build ./...
6. Test
# Run tests for the changed package
go test -timeout 10m ./your-package/...
# Run the full test suite
go test -timeout 10m ./...
If working on oracle/ tests, the substrate plugin must be available:
# Download the plugin (only needed once)
./scripts/obtain-plugin.sh
# Or via make
make plugin
7. Verify Round-Trip
If your change adds a new public API, verify it with a simple test. If modifying behavior, write a test that captures the expected behavior first (TDD).
Key Reminders
- Use
testifyfor assertions in tests (existing pattern in codebase) - The
svcerrpackage maps errors to gRPC status codes — use it for error handling - Context propagation uses
grpclogging.AddLogrusField(ctx, key, value)for structured logging - Oracle tests need
SUBSTRATEHCP_FILEenv var pointing to the plugin binary (set by Makefile)
Checklist
- Code builds cleanly (
go build ./...) - Lint passes (
golangci-lint run) - Tests pass for changed packages
- Full test suite passes (
go test -timeout 10m ./...) - New files have copyright header
- No generated files were manually edited
Converted and distributed by TomeVault — claim your Tome and manage your conversions.