Contributing

Thank you for your interest in contributing to Rack Gateway! This guide covers everything you need to know to submit quality contributions.

Getting Started

1. Fork the repository

   Fork docspring/rack-gateway on GitHub.

2. Clone your fork

   git clone https://github.com/YOUR_USERNAME/rack-gateway.git
   cd rack-gateway

3. Set up development environment

   Follow the Local Setup guide.

4. Create a branch

   git checkout -b feature/your-feature-name

Development Workflow

Before You Code

1. Check existing issues - See if your feature/bug is already being worked on
2. Open an issue - For significant changes, discuss the approach first
3. Keep scope small - Focused PRs are easier to review

While Coding

# Make your changes, then verify:

# 1. Run linting (with auto-fix)
task lint:fix

# 2. Run the tests for what you changed
task go:test:unit
task web:test
task web:e2e -- --grep "the flow you changed"

Never bypass the git hooks (--no-verify): the pre-commit hook formats, lints, and checks duplication and file lengths.

Before Submitting

1. CI passes - CI runs the full suite (task ci) on every push, and a PR merges only when it’s green
2. Code is formatted - Run task lint:fix
3. Commit messages are clear - Follow commit conventions below
4. Documentation is updated - For new features or changes

Code Standards

Go Code

Style

• Follow Effective Go guidelines
• Use gofmt and goimports (handled by task lint:fix)
• Maximum line length: 120 characters
• Maximum function length: 100 lines and 50 statements, and cognitive complexity 15
• No panic, time.Sleep or fmt.Print* outside CLI output: return errors, use contexts with timeouts, and log
• No //nolint comments: fix the code. The only exceptions are //nolint:lll on struct tag lines gofmt can’t break, and gosec exceptions that name the rule and the reason (// #nosec G402 -- racks have no public CA chain)

Naming

// Good: Clear, descriptive names
func CreateUserSession(user *User) (*Session, error)
func ValidateAPIToken(token string) (*Token, error)

// Bad: Unclear abbreviations
func CrtUsrSess(u *User) (*Session, error)

Error Handling

// Good: Wrap errors with context
if err := db.Query(query); err != nil {
    return fmt.Errorf("failed to fetch user %s: %w", userID, err)
}

// Bad: Generic error messages
if err := db.Query(query); err != nil {
    return err
}

Comments

// Good: Explain WHY, not WHAT
// UseRoundRobin distributes load across servers to prevent
// any single server from being overwhelmed during peak traffic.
func UseRoundRobin() LoadBalancer { ... }

// Bad: Restating the code
// GetUser gets a user
func GetUser(id string) *User { ... }

TypeScript/React Code

Style

• Use Biome for formatting and linting; // biome-ignore comments aren’t allowed
• Prefer functional components with hooks
• Use TypeScript strict mode
• Use the generated API client in web/src/api/ (task generate after changing Go handlers)

Component Structure

// Good: Clear component organization
interface Props {
  user: User;
  onLogout: () => void;
}

export function UserMenu({ user, onLogout }: Props) {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <div className="user-menu">
      {/* Component content */}
    </div>
  );
}

Error Handling

// Good: Use React Query for data fetching with error handling
const { data, error, isLoading } = useQuery({
  queryKey: ['user', userId],
  queryFn: () => fetchUser(userId),
});

if (error) {
  return <ErrorMessage error={error} />;
}

File Limits

Strictly Enforced

These limits are enforced by CI and must be followed.

File Type	Max Lines
Go code files	500 lines
Go test files	1000 lines
TypeScript/TSX code	500 lines
TypeScript test files	1000 lines

If a file approaches these limits, refactor into smaller modules. Production code may not duplicate 10 or more lines (task duplication).

Commit Conventions

Format

type(scope): short description

Longer description if needed.

Types

Type	Description
feat	New feature
fix	Bug fix
docs	Documentation only
style	Formatting, no code change
refactor	Code restructuring
test	Adding/updating tests
chore	Maintenance tasks

Examples

feat(auth): add WebAuthn support for passwordless login

fix(proxy): handle timeout errors gracefully

docs(readme): update installation instructions

refactor(rbac): extract permission checking to separate module

Pull Request Guidelines

PR Title

Use the same format as commit messages:

feat(auth): add WebAuthn support

PR Description

Include:

1. Summary - What does this PR do?
2. Motivation - Why is this change needed?
3. Testing - How was this tested?
4. Screenshots - For UI changes

PR Template

## Summary
Brief description of what this PR does.

## Motivation
Why is this change needed?

## Changes
- Change 1
- Change 2

## Testing
- [ ] Unit tests added/updated
- [ ] Integration tests pass
- [ ] E2E tests pass
- [ ] Manual testing completed

## Screenshots (if applicable)

Review Process

1. Automated checks - CI must pass
2. Code review - At least one maintainer approval
3. Documentation - Updates if needed
4. Merge - A maintainer merges once CI is green

Security Guidelines

Reporting Vulnerabilities

Danger

Do NOT open public issues for security vulnerabilities.

Report them privately: report a vulnerability on GitHub, or email security@docspring.com. See the security policy.

Secure Coding Practices

1. Input Validation

   • Validate all user input
   • Use parameterized queries (never string concatenation)
   • Sanitize output for XSS prevention

2. Authentication

   • Never log sensitive data (tokens, passwords)
   • Use constant-time comparison for secrets
   • Implement rate limiting on auth endpoints

3. Dependencies

   • Keep dependencies updated
   • Review security advisories
   • Run task go:sec:vuln (govulncheck) and task sec:js (bun audit of the web, docs and mock OAuth packages); CI fails on any high or critical advisory

Testing Requirements

Coverage Expectations

• New features must include tests
• Bug fixes should include regression tests
• Aim for meaningful coverage, not just line coverage

Test Types

Change Type	Required Tests
New API endpoint	Unit + Integration + E2E
Bug fix	Regression test
UI component	Unit test + E2E (if user-facing)
Refactoring	Existing tests must pass

Documentation

When to Update Docs

• New features
• Changed behavior
• New configuration options
• API changes

Documentation Location

Content	Location
API docs	OpenAPI spec in Go handlers
User guides	docs/src/content/docs/
Code docs	Inline comments
Architecture	docs/src/content/docs/concepts/

Getting Help

Resources

• Development Guide
• Testing Guide
• API Reference

Communication

• GitHub Issues - Bug reports, feature requests, questions
• Pull Requests - Code review, feedback

License

Rack Gateway is licensed under the Apache License 2.0 (LICENSE). By contributing, you agree that your contributions are licensed under it.

Thank you for contributing to Rack Gateway!