Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
294 lines (208 loc) · 7.47 KB

CONTRIBUTING.md

File metadata and controls

294 lines (208 loc) · 7.47 KB

Contributing to Comic Vine SDK

Thank you for your interest in contributing to the Comic Vine SDK! This document provides guidelines and information to help you contribute effectively to the project.

Table of Contents

Code of Conduct

This project adheres to a Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to allymurray88@gmail.com.

Getting Started

Prerequisites

Before you begin, ensure you have the following installed:

  • Node.js: Version 20.0.0 or higher
  • pnpm: Version 9.15.4+ (specified in package.json) 
    npm install -g pnpm@9.15.4

Development Setup

  1. Fork and Clone

    git clone https://github.com/your-username/comic-vine.git
cd comic-vine

  2. Install Dependencies

    pnpm install

  3. Verify Setup

    pnpm test

If all tests pass, you're ready to start developing!

Development Workflow

Creating a Branch

  1. Create a feature branch from main:

    git checkout -b feature/your-feature-name
# or
git checkout -b fix/issue-description

  2. Use descriptive branch names:

    • feature/add-search-pagination
    • fix/handle-rate-limiting
    • docs/update-readme-examples

Making Changes

  1. Write Code: Follow the Code Standards below
  2. Add Tests: Ensure new functionality has corresponding tests
  3. Run Tests: pnpm test to run tests and linting
  4. Build: pnpm compile to ensure your changes compile correctly

Commit Messages

Follow conventional commit format:

type(scope): description

[optional body]

[optional 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:

feat(resources): add pagination support to character list
fix(http-client): handle network timeout errors
docs(readme): update installation instructions

Code Standards

TypeScript Guidelines

  • Type Safety: Prefer explicit types over any
  • Interfaces: Use interfaces for object shapes
  • Generics: Leverage generics for reusable components
  • Strict Mode: The project uses strict TypeScript settings

Code Style

The project uses ESLint and Prettier for code formatting:

# Auto-fix linting issues and format code
pnpm lint

# Check linting without fixing
npx eslint src --ext .ts

Key Style Rules:

  • Use camelCase for variables and functions
  • Use PascalCase for classes and interfaces
  • Prefer const over let when possible
  • Use meaningful variable names
  • Add JSDoc comments for public APIs

Import Organization

Imports should be organized as follows:

// 1. Built-in Node.js modules
import { readFile } from 'fs/promises';

// 2. External dependencies
import axios from 'axios';
import { z } from 'zod';

// 3. Internal modules (ordered alphabetically)
import { BaseResource } from './base-resource';
import { HttpClient } from './http-client';

Testing

Running Tests

# Run all tests with linting
pnpm test

# Run tests only (without linting)
pnpm test:run

# Run tests in watch mode
npx vitest --dir=src

Writing Tests

  1. Location: Place test files alongside source files with .test.ts extension
  2. Naming: Use descriptive test names that explain the behavior being tested
  3. Structure: Follow Arrange-Act-Assert pattern

Example Test:

import { describe, test, expect } from 'vitest';

describe('ResourceName', () => {
  test('should return correct data when field list is specified', async () => {
    // Arrange
    const expectedFields = ['id', 'name'];

    // Act
    const result = await resource.retrieve(123, { fieldList: expectedFields });

    // Assert
    expect(Object.keys(result)).toEqual(expectedFields);
  });
});

Test Coverage

  • Write tests for all new functionality
  • Include both success and error scenarios
  • Mock external dependencies using nock for HTTP requests
  • Test files are located in src/__mocks__/ for mock data

Submitting Changes

Pull Request Process

  1. Update Documentation: Ensure README, JSDoc, and other docs reflect your changes

  2. Verify Quality Checks: All checks must pass before merging

    pnpm test:run  # All tests pass
pnpm lint      # No linting errors
pnpm compile   # Code compiles successfully

  3. Create Pull Request:

    • Use a descriptive title
    • Reference any related issues
    • Provide clear description of changes
    • Include examples if adding new features

  4. Review Process:

    • Maintainers will review your PR
    • Address any feedback promptly
    • See CODE_REVIEW.md for review criteria

Pre-commit Hooks

The project uses Husky and lint-staged to ensure code quality:

  • Auto-formatting: Prettier formats code on commit
  • Linting: ESLint checks are enforced
  • Type checking: TypeScript compilation is verified

If pre-commit hooks fail, fix the issues before committing:

pnpm lint  # Fix linting issues
git add .  # Stage the fixes
git commit # Try committing again

Project Structure

src/
├── comic-vine.ts              # Main SDK class
├── errors/                    # Custom error classes
├── http-client/               # HTTP client and URL builder
├── options/                   # Configuration options
├── resources/                 # API resource implementations
│   ├── base-resource.ts       # Base class for all resources
│   ├── character/             # Character-specific code
│   ├── issue/                 # Issue-specific code
│   └── ...                    # Other Comic Vine resources
├── types/                     # TypeScript type definitions
└── utils/                     # Utility functions

Adding New Resources

When adding support for a new Comic Vine API resource:

  1. Create a new directory under src/resources/
  2. Implement the resource class extending BaseResource
  3. Add TypeScript types in a types/ subdirectory
  4. Write comprehensive tests
  5. Update the main ComicVine class to include the new resource
  6. Add mock data for testing

Resources

Documentation

Getting Help

  • Issues: GitHub Issues
  • Discussions: Use GitHub Discussions for questions

Development Tools

Thank you for contributing to Comic Vine SDK! Your contributions help make this library better for everyone. 🚀