Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
310 lines (221 loc) · 6.29 KB

CONTRIBUTING.md

File metadata and controls

310 lines (221 loc) · 6.29 KB

Contributing to LazyCache Platform

Thank you for your interest in contributing to this project. This document outlines the guidelines and best practices for contributing.

Table of Contents

Code of Conduct

By participating in this project, you agree to maintain a respectful and inclusive environment. Be professional, constructive, and considerate in all interactions.

Getting Started

Prerequisites

Ensure you have the following installed:

  • Go 1.21+
  • Node.js 20+
  • Docker & Docker Compose
  • Terraform 1.6+
  • Make

Setting Up Development Environment

  1. Clone the repository

    git clone git@github.com:canerdogan/upstash.git
cd upstash

  2. Start the development environment

    make dev-up

  3. Verify everything is running

    docker-compose ps

Development Workflow

Branch Naming Convention

Use the following prefixes for branch names:

  • feature/ - New features (e.g., feature/add-billing-api)
  • fix/ - Bug fixes (e.g., fix/auth-token-expiry)
  • refactor/ - Code refactoring (e.g., refactor/database-layer)
  • docs/ - Documentation updates (e.g., docs/api-endpoints)
  • chore/ - Maintenance tasks (e.g., chore/update-dependencies)

Workflow Steps

  1. Create a new branch from main

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

  2. Make your changes

  3. Write/update tests

  4. Run tests locally

    make test

  5. Commit your changes (see Commit Guidelines)

  6. Push and create a Pull Request

Coding Standards

Go Code

  • Follow Effective Go guidelines
  • Use gofmt for formatting
  • Run golangci-lint before committing 
    make api-lint
  • Write meaningful comments for exported functions
  • Keep functions small and focused
  • Handle errors explicitly - don't ignore them

Example

// CreateDatabase provisions a new Redis database for the user.
// It returns the database details or an error if provisioning fails.
func (s *DatabaseService) CreateDatabase(ctx context.Context, req CreateDatabaseRequest) (*Database, error) {
    // Validate request
    if err := req.Validate(); err != nil {
        return nil, fmt.Errorf("invalid request: %w", err)
    }

    // Create database
    db, err := s.repo.Create(ctx, req)
    if err != nil {
        return nil, fmt.Errorf("failed to create database: %w", err)
    }

    return db, nil
}

TypeScript/React Code

  • Use TypeScript for all new code
  • Follow the existing code style
  • Use functional components with hooks
  • Keep components small and reusable
  • Use proper typing - avoid any

Example

interface DatabaseCardProps {
  database: Database;
  onDelete: (id: string) => void;
}

export const DatabaseCard: React.FC<DatabaseCardProps> = ({ database, onDelete }) => {
  const handleDelete = () => {
    if (confirm('Are you sure?')) {
      onDelete(database.id);
    }
  };

  return (
    <div className="p-4 border rounded-lg">
      <h3 className="font-bold">{database.name}</h3>
      <button onClick={handleDelete}>Delete</button>
    </div>
  );
};

Terraform Code

  • Use consistent formatting (terraform fmt)
  • Organize resources logically
  • Use variables for configurable values
  • Add descriptions to variables and outputs
  • Use modules for reusable components

Commit Guidelines

We follow the Conventional Commits specification.

Format

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Types

  • feat - New feature
  • fix - Bug fix
  • docs - Documentation changes
  • style - Code style changes (formatting, etc.)
  • refactor - Code refactoring
  • test - Adding or updating tests
  • chore - Maintenance tasks

Examples

feat(api): add database deletion endpoint

fix(auth): resolve JWT token refresh race condition

docs(readme): update installation instructions

refactor(dashboard): extract common form components

Rules

  • Use imperative mood ("add" not "added")
  • Don't capitalize the first letter
  • No period at the end of the subject line
  • Keep the subject line under 72 characters
  • Reference issues in the footer when applicable

Pull Request Process

Before Submitting

  • Tests pass locally (make test)
  • Code is linted (make api-lint)
  • Documentation is updated if needed
  • Commit messages follow guidelines
  • Branch is up to date with main

PR Description Template

## Summary
Brief description of the changes.

## Changes
- Change 1
- Change 2

## Testing
How to test these changes.

## Related Issues
Closes #123

Review Process

  1. All PRs require at least one approval
  2. All CI checks must pass
  3. Resolve all review comments before merging
  4. Squash commits when merging if there are many small commits

Testing

Go Tests

# Run all tests
make api-test

# Run tests with coverage
make api-test-coverage

# Run specific test
cd services/api && go test -v ./internal/handlers -run TestCreateDatabase

React Tests

# Run all tests
make dashboard-test

# Run tests in watch mode
cd services/dashboard && npm run test:watch

Writing Good Tests

  • Test one thing per test
  • Use descriptive test names
  • Include both positive and negative cases
  • Mock external dependencies
  • Keep tests fast and isolated

Go Example

func TestDatabaseService_Create(t *testing.T) {
    t.Run("creates database successfully", func(t *testing.T) {
        // Arrange
        mockRepo := NewMockRepository()
        service := NewDatabaseService(mockRepo)

        // Act
        db, err := service.Create(context.Background(), validRequest)

        // Assert
        assert.NoError(t, err)
        assert.NotEmpty(t, db.ID)
    })

    t.Run("returns error for invalid request", func(t *testing.T) {
        // ...
    })
}

Questions?

If you have questions about contributing, please reach out to the development team.