Contributing to Claude Code Analytics

November 23, 2025 · View on GitHub

Thank you for your interest in contributing to Claude Code Analytics! This document provides guidelines and instructions for contributing to the project.

Code of Conduct
Getting Started
How to Contribute
Development Guidelines
Pull Request Process
Reporting Issues

Code of Conduct

Our Standards

We are committed to providing a welcoming and inspiring community for all. Please be respectful and constructive in your interactions.

Examples of positive behavior:

Using welcoming and inclusive language
Being respectful of differing viewpoints
Gracefully accepting constructive criticism
Focusing on what is best for the community

Unacceptable behavior:

Trolling, insulting comments, or personal attacks
Public or private harassment
Publishing others' private information
Other conduct that could reasonably be considered inappropriate

Getting Started

Prerequisites

Before contributing, ensure you have:

Node.js 18 or higher
PostgreSQL 14 or higher
Git installed and configured
Familiarity with TypeScript, React, and PostgreSQL

Initial Setup

Fork the repository

# Click "Fork" on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/claude-code-analytics.git
cd claude-code-analytics

Add upstream remote

git remote add upstream https://github.com/istealersn-dev/claude-code-analytics.git

Install dependencies

npm install
cd frontend && npm install && cd ..

Set up development environment

# Create database
createdb claude_code_analytics

# Run schema
psql -d claude_code_analytics -f schema.sql

# Configure environment
cp .env.example .env
cp frontend/.env.example frontend/.env.local
# Edit .env files with your settings

Verify setup
```
npm run dev:all
```
Visit http://localhost:5173 to confirm everything works.

How to Contribute

Ways to Contribute

🐛 Report bugs - Found an issue? Let us know!
✨ Suggest features - Have an idea? We'd love to hear it!
📝 Improve documentation - Clarify, expand, or fix docs
🔧 Fix bugs - Help squash those pesky bugs
⚡ Add features - Implement new functionality
🎨 Improve UI/UX - Make the dashboard more beautiful
✅ Write tests - Improve test coverage

Good First Issues

Look for issues labeled good first issue or help wanted - these are great starting points for new contributors.

Development Guidelines

Code Style

We use strict TypeScript and Biome for code quality:

# Format code
npm run format

# Lint code
npm run lint

# Type check
npm run type-check

Naming Conventions

Follow these conventions consistently:

Type	Convention	Example
Variables/Functions	camelCase	`getUserData`, `isLoading`
Components/Types	PascalCase	`DashboardCard`, `SessionData`
Constants	SCREAMING_SNAKE_CASE	`MAX_RETRIES`, `API_BASE_URL`
Files	kebab-case	`session-list.tsx`, `api-client.ts`
CSS Classes	kebab-case	`.card-header`, `.btn-primary`

Component Guidelines

Single Responsibility: Each component does one thing well
Explicit Props: Define all props with TypeScript interfaces
Composition: Prefer composition over complex components
Error Boundaries: Wrap risky operations

Example:

interface CardProps {
  title: string
  children: React.ReactNode
  className?: string
}

export function Card({ title, children, className = '' }: CardProps) {
  return (
    <div className={`rounded-lg border p-4 ${className}`}>
      <h3 className="text-lg font-semibold">{title}</h3>
      {children}
    </div>
  )
}

Testing Requirements

Write tests for new features
Update tests when modifying existing code
Ensure all tests pass before submitting PR

# Run tests
npm run test

# Run with coverage
npm run test:coverage

Commit Message Format

Use Conventional Commits:

<type>(<scope>): <subject>

<body>

<footer>

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:

git commit -m "feat(dashboard): add session duration chart"
git commit -m "fix(sync): handle empty JSONL files correctly"
git commit -m "docs(api): update authentication examples"

Documentation

Update relevant documentation when making changes
Add JSDoc comments for complex functions
Include examples for new features
Keep README and docs in sync

Pull Request Process

Before Submitting

Update your fork

git fetch upstream
git checkout main
git merge upstream/main

Create a feature branch

git checkout -b feature/your-feature-name

Make your changes
- Follow code style guidelines
- Write/update tests
- Update documentation

Run quality checks

npm run test           # All tests pass
npm run type-check     # No type errors
npm run lint           # No lint errors
npm run format         # Code formatted

Commit your changes

git add .
git commit -m "feat: your descriptive commit message"

Push to your fork

git push origin feature/your-feature-name

Submitting the PR

Go to your fork on GitHub
Click "New Pull Request"
Select your feature branch
Fill out the PR template:

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## How Has This Been Tested?
Describe testing approach

## Checklist
- [ ] Tests pass
- [ ] Code follows style guidelines
- [ ] Documentation updated
- [ ] No breaking changes (or documented)

PR Review Process

Automated Checks: CI will run tests and linting
Code Review: Maintainers will review your code
Feedback: Address any requested changes
Approval: Once approved, your PR will be merged

After Your PR is Merged

Delete your branch

git branch -d feature/your-feature-name
git push origin --delete feature/your-feature-name

Update your main branch

git checkout main
git pull upstream main

Reporting Issues

Bug Reports

Use the bug report template and include:

Description: Clear description of the bug

Steps to Reproduce:

1. Go to '...'
2. Click on '...'
3. See error

Expected Behavior: What should happen
Actual Behavior: What actually happens
Environment:
- OS: [e.g., macOS 14.0]
- Node.js version: [e.g., 18.17.0]
- PostgreSQL version: [e.g., 14.9]
- Browser: [e.g., Chrome 119]
Screenshots: If applicable
Error Messages: Full error output