Contributing Guide

​

Getting Started

​

Prerequisites

• Completed the local development setup
• Read the architecture overview
• Familiarized yourself with the codebase structure

​

Contribution Workflow

git checkout main
git pull origin main
git checkout -b feature/your-feature-name

make check

git add .
git commit -m "Add feature: brief description"

git push origin feature/your-feature-name

​

Pull Request Guidelines

​

Keep PRs Focused and Small

• Add search endpoint for prompts
• Fix JWT token expiry validation
• Update API documentation for versions endpoint

• Mixing multiple unrelated changes
• Large refactors combined with new features
• Reformatting entire files alongside logic changes

​

Include Tests or Verification Notes

1. Automated tests (preferred)
   func TestPromptCreate(t *testing.T) {
       // Test implementation
   }
   
2. Manual testing steps
   ## Testing
   1. Start API server
   2. Run: `curl -X POST http://localhost:8080/v1/prompts ...`
   3. Verify response contains created prompt
   
3. Verification notes (for docs/config changes)
   ## Verification
   - Rendered documentation locally
   - Verified all links work
   - Checked code examples run successfully
   

​

Update Documentation

• API contracts change (update docs/api/openapi.yaml)
• New features are added (update relevant .md files)
• Configuration options change (update .env.example and docs)
• Architecture changes (update docs/architecture.md)

​

Code Quality Standards

​

Required Pre-PR Checks

gofmt -w ./...
# or
make fmt

​

Code Formatting

# Format all Go files
gofmt -w $(go list -f '{{.Dir}}' ./...)

​

Testing Guidelines

• New business logic
• Bug fixes (regression tests)
• Complex validation logic
• Repository methods

func TestPromptRepository_Create(t *testing.T) {
    db := setupTestDB(t)
    repo := prompts.NewGORMRepository(db)
    
    prompt := &prompts.Prompt{
        Name:        "test-prompt",
        Description: "A test prompt",
        OwnerID:     "user_123",
    }
    
    created, err := repo.Create(context.Background(), prompt, []string{"tag1"})
    assert.NoError(t, err)
    assert.NotEmpty(t, created.ID)
    assert.Equal(t, "test-prompt", created.Name)
}

​

API Change Policy

​

OpenAPI Specification Updates

// internal/prompts/model.go
type Prompt struct {
    ID          string    `json:"id"`
    Name        string    `json:"name"`
    Description string    `json:"description"`
    Tags        []string  `json:"tags"` // NEW FIELD
}

​

Error Response Consistency

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  }
}

​

Versioning

// ✓ Good
v1.GET("/prompts", handler.List)
v1.POST("/prompts", handler.Create)

// ✗ Avoid (unless introducing v2)
v2.GET("/prompts", handler.ListV2)

​

Commit Style

​

Commit Message Format

Add search endpoint for prompts
Fix JWT token expiry validation
Update OpenAPI spec for versions endpoint
Refactor storage client interface

​

Explain the “Why”, Not Just the “What”

Add rate limiting to upload endpoint

Prevents abuse by limiting users to 10 uploads per minute.
Rejected requests return 429 with Retry-After header.

Add rate limiting

​

Atomic Commits

• ✓ One commit per feature/fix
• ✓ All tests pass at each commit
• ✗ Multiple unrelated changes in one commit
• ✗ “Fix previous commit” commits (use git commit --amend instead)

​

Documentation Style

​

Writing Documentation

1. Prefer short sections with concrete examples
   ## Upload a Prompt
   
   ```bash
   curl -X POST http://localhost:8080/v1/prompts \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"name": "my-prompt", "description": "A test prompt"}'
   
2. Use real request/response examples Show actual API responses, not placeholders
3. Keep docs aligned with implementation Documentation should reflect current behavior, not planned features
4. Use clear headings and structure
   • Use ## for main sections
   • Use ### for subsections
   • Use code blocks with language hints

​

Code Review Process

​

What Reviewers Look For

1. Code Quality
   • Follows Go best practices
   • Properly formatted with gofmt
   • Clear variable and function names
2. Testing
   • Tests cover new functionality
   • Edge cases are handled
   • Tests are readable and maintainable
3. Documentation
   • API changes include OpenAPI updates
   • README or docs updated if needed
   • Code comments for complex logic
4. Architecture
   • Follows existing patterns
   • Respects module boundaries
   • Uses interfaces for dependencies

​

Responding to Feedback

• Address all reviewer comments
• Ask questions if feedback is unclear
• Push new commits (don’t force-push during review)
• Mark conversations as resolved when addressed

​

Common Tasks

​

Adding a New API Endpoint

v1.GET("/prompts/:id", promptsHandler.Get)

// internal/prompts/handler.go
func (h *Handler) Get(c *gin.Context) {
    id := c.Param("id")
    // Implementation...
}

// internal/prompts/repository.go
func (r *GORMRepository) FindByID(ctx context.Context, id string) (*Prompt, error) {
    // Implementation...
}

# docs/api/openapi.yaml
/prompts/{id}:
  get:
    summary: Get prompt by ID
    # ...

func TestHandler_Get(t *testing.T) {
    // Test implementation...
}

​

Adding a Database Migration

touch migrations/003_add_column.up.sql
touch migrations/003_add_column.down.sql

-- migrations/003_add_column.up.sql
ALTER TABLE prompts ADD COLUMN visibility VARCHAR(20) DEFAULT 'public';

// internal/prompts/model.go
type Prompt struct {
    // ...
    Visibility string `gorm:"default:public"`
}

make reset  # Clear database
make api    # Migrations run automatically

​

Getting Help

​

Questions or Issues?

• General questions: Open a discussion on GitHub
• Bug reports: Open an issue with reproduction steps
• Feature requests: Open an issue with use case description
• Security issues: Email [email protected] (do not open public issues)

​

Resources

• Local Development Setup
• Architecture Overview
• API Documentation
• Repository Structure

​

License