Skip to content

contributing.md

Latest commit

 

History

History
497 lines (361 loc) · 10.6 KB

contributing.md

File metadata and controls

497 lines (361 loc) · 10.6 KB
Raw

Contributing Guide

Thank you for your interest in contributing to the Scheduling SDK! This guide will help you get set up for development and understand our contribution process.

Table of Contents

Development Setup

Prerequisites

  • Bun: v1.0+ (recommended runtime)
  • Node.js: v18+ (alternative runtime)
  • TypeScript: v5+ (peer dependency)
  • Git: Latest version

Installation

  1. Fork and Clone

    git clone https://github.com/your-username/scheduling-sdk.git
cd scheduling-sdk

  2. Install Dependencies

    bun install

  3. Verify Setup

    bun run build
bun test
bun run typecheck
bun run lint

Development Commands

# Development mode with file watching
bun run dev

# Build for distribution
bun run build

# Run tests
bun test

# Run tests in watch mode
bun test --watch

# Type checking
bun run typecheck

# Linting
bun run lint

# Code formatting
bun run prettier

# Pre-publish checks
bun run prepublishOnly

Project Structure

scheduling-sdk/
├── src/                    # Source code
│   ├── core/              # Main Scheduler class
│   ├── helpers/           # Utility functions by domain
│   │   ├── busy-time/     # Busy time operations
│   │   ├── slot/          # Slot generation and filtering
│   │   └── time/          # Date/time utilities
│   ├── types/             # TypeScript type definitions
│   ├── utils/             # Shared constants and utilities
│   ├── validators/        # Input validation functions
│   └── index.ts           # Main entry point
├── tests/                 # Test files (mirrors src structure)
├── docs/                  # Documentation
├── dist/                  # Build output (generated)
└── package.json           # Project configuration

Module Organization

  • src/core/: Core scheduling logic and main API
  • src/helpers/: Domain-specific helper functions
  • src/types/: TypeScript interfaces and type definitions
  • src/validators/: Input validation and error handling
  • src/utils/: Shared constants and utility functions

Development Workflow

1. Feature Development

  1. Create Feature Branch

    git checkout -b feature/your-feature-name

  2. Implement Feature

    • Write code following existing patterns
    • Add/update types as needed
    • Include input validation

  3. Write Tests

    • Unit tests for new functions
    • Integration tests for complex features
    • Edge case testing

  4. Update Documentation

    • API documentation for new public methods
    • Usage examples for new features
    • Update README if needed

2. Bug Fixes

  1. Create Bug Fix Branch

    git checkout -b fix/bug-description

  2. Reproduce Bug

    • Create failing test case
    • Understand root cause

  3. Implement Fix

    • Fix the issue
    • Ensure tests pass
    • Verify no regression

  4. Add Regression Test

    • Ensure bug won't reoccur
    • Test edge cases

Testing Guidelines

Test Structure

import { describe, it, expect, beforeEach } from 'bun:test'

describe('Feature Name', () => {
    describe('method name', () => {
        it('should handle basic case', () => {
            // Arrange
            const input = setupTestData()

            // Act
            const result = methodUnderTest(input)

            // Assert
            expect(result).toEqual(expectedOutput)
        })

        it('should handle edge case', () => {
            // Test edge cases
        })

        it('should throw on invalid input', () => {
            expect(() => methodUnderTest(invalidInput)).toThrow()
        })
    })
})

Test Categories

Unit Tests

  • Test individual functions in isolation
  • Mock dependencies where appropriate
  • Focus on edge cases and error conditions

Integration Tests

  • Test feature workflows end-to-end
  • Use real dependencies
  • Verify complex interactions

Performance Tests

  • Benchmark critical paths
  • Ensure performance targets are met
  • Test with realistic data sizes

Test Data

Use consistent test data patterns:

// Standard test dates
const testDate = new Date('2024-01-15T09:00:00Z')
const workDayStart = new Date('2024-01-15T09:00:00Z')
const workDayEnd = new Date('2024-01-15T17:00:00Z')

// Standard test options
const basicOptions = {
    slotDuration: 60,
    slotSplit: 60,
    padding: 0,
    offset: 0,
}

Coverage Requirements

  • Line Coverage: 95%+
  • Branch Coverage: 90%+
  • Function Coverage: 100%

Run coverage with:

bun test --coverage

Code Style

TypeScript Guidelines

// ✅ Use explicit interfaces
interface SchedulingOptions {
    slotDuration: number
    slotSplit?: number
}

// ✅ Use proper typing
function generateSlots(options: SchedulingOptions): TimeSlot[] {
    // implementation
}

// ✅ Use readonly for immutable data
interface TimeSlot {
    readonly start: Date
    readonly end: Date
}

// ❌ Avoid any types
function badFunction(data: any): any {
    return data
}

Naming Conventions

  • Files: kebab-case.ts (e.g., slot-generator.ts)
  • Functions: camelCase (e.g., generateSlots)
  • Classes: PascalCase (e.g., Scheduler)
  • Constants: UPPER_SNAKE_CASE (e.g., MS_PER_MINUTE)
  • Types/Interfaces: PascalCase (e.g., TimeSlot)

Code Organization

// File structure order:
// 1. Imports
import type { TimeSlot } from '../types/scheduling.types.ts'
import { MS_PER_MINUTE } from '../utils/constants.ts'

// 2. Type definitions (if any)
interface LocalOptions {
    // ...
}

// 3. Main implementation
export function mainFunction() {
    // ...
}

// 4. Helper functions (non-exported)
function helperFunction() {
    // ...
}

Error Handling

// ✅ Provide descriptive error messages
if (duration <= 0) {
    throw new Error('Slot duration must be a positive number')
}

// ✅ Validate at function boundaries
export function validateTimeRange(start: Date, end: Date): void {
    if (start >= end) {
        throw new Error('Start time must be before end time')
    }
}

// ✅ Use appropriate error types
class ValidationError extends Error {
    constructor(message: string) {
        super(message)
        this.name = 'ValidationError'
    }
}

Performance Considerations

// ✅ Prefer immutable operations where possible
const newArray = [...existingArray, newItem]

// ✅ Use efficient algorithms
// Sort once, then process
const sortedBusyTimes = busyTimes.sort((a, b) => a.start.getTime() - b.start.getTime())

// ✅ Avoid unnecessary object creation in loops
for (const item of items) {
    // Reuse variables where possible
}

Pull Request Process

1. Before Submitting

  • All tests pass
  • Code is formatted (bun run prettier)
  • Linting passes (bun run lint)
  • Type checking passes (bun run typecheck)
  • Documentation is updated
  • CHANGELOG is updated (for features)

2. PR Description

Use this template:

## Description

Brief description of the change and why it's needed.

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update

## Testing

- [ ] New tests added for new functionality
- [ ] All existing tests pass
- [ ] Edge cases covered

## Checklist

- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] No breaking changes (or breaking changes documented)

3. Review Process

  1. Automated Checks: CI must pass
  2. Code Review: At least one maintainer approval
  3. Manual Testing: Verify functionality works as expected
  4. Documentation Review: Ensure docs are accurate and complete

4. Merge Requirements

  • All CI checks pass
  • At least one approving review
  • No requested changes outstanding
  • Branch is up to date with main

Issue Reporting

Bug Reports

Use the bug report template:

**Describe the bug**
A clear description of what the bug is.

**To Reproduce**
Steps to reproduce the behavior:

1. Create scheduler with '...'
2. Call method '...'
3. See error

**Expected behavior**
What you expected to happen.

**Code example**

```typescript
// Minimal reproduction case
```

Environment:

  • Bun version: [e.g. 1.0.15]
  • Node version: [e.g. 18.17.0]
  • OS: [e.g. macOS 13.4]
  • SDK version: [e.g. 1.2.3]

### Feature Requests

Use the feature request template:

```markdown
**Is your feature request related to a problem?**
A clear description of what the problem is.

**Describe the solution you'd like**
A clear description of what you want to happen.

**Describe alternatives you've considered**
Other solutions you've considered.

**Additional context**
Any other context about the feature request.

**Code example**
```typescript
// Example of how the feature might be used


### Security Issues

For security vulnerabilities:
1. **Do not** create a public issue
2. Email security concerns to: [security-email]
3. Include detailed reproduction steps
4. Allow time for responsible disclosure

## Development Tips

### Debugging

```typescript
// Use console.log sparingly in production code
// Prefer proper error messages and validation

// For debugging during development:
console.log('Debug: slot count', slots.length)
console.time('Performance check')
// ... code to measure
console.timeEnd('Performance check')

Testing New Features

# Test your changes against real scenarios
bun run build
cd test-project
npm link ../scheduling-sdk
# Test integration

Documentation

  • Keep documentation in sync with code changes
  • Include practical examples
  • Update type definitions
  • Consider performance implications

Getting Help

  • Questions: Create a discussion or issue
  • Real-time help: [Community channel if available]
  • Documentation: Check existing docs first
  • Examples: Look at test files for usage patterns

Thank you for contributing to the Scheduling SDK! Your contributions help make scheduling easier for developers everywhere.