Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
317 lines (236 loc) · 7.42 KB

CONTRIBUTING.md

File metadata and controls

317 lines (236 loc) · 7.42 KB
Raw

Contributing to coveralls-next

Thank you for your interest in contributing to coveralls-next! This document provides guidelines and instructions for contributing.

Table of Contents

Code of Conduct

By participating in this project, you agree to maintain a respectful and inclusive environment for all contributors.

Getting Started

  1. Fork the repository on GitHub
  2. Clone your fork locally: 
    git clone https://github.com/YOUR_USERNAME/coveralls-next.git
cd coveralls-next
  3. Add the upstream remote: 
    git remote add upstream https://github.com/nickmerwin/coveralls-next.git

Development Setup

Prerequisites

  • Node.js 18.x or higher
  • npm 8.x or higher
  • Git

Installation

# Install dependencies
npm install

# Run tests to verify setup
npm test

# Run tests with coverage
npm run test-cov

Project Structure

coveralls-next/
├── bin/
│   └── coveralls.js          # CLI entry point
├── lib/
│   ├── convertLcovToCoveralls.js  # LCOV to Coveralls format conversion
│   ├── detectLocalGit.js          # Local git repository detection
│   ├── fetchGitData.js            # Git metadata extraction
│   ├── getOptions.js              # Configuration and options parsing
│   ├── handleInput.js             # Input processing orchestration
│   ├── logger.js                  # Logging utility
│   └── sendToCoveralls.js         # API communication
├── test/                      # Test files (mirror lib/ structure)
└── index.js                   # Main entry point

Coding Standards

Style Guide

  • JavaScript Standard: We follow Node.js best practices
  • Indentation: 2 spaces (no tabs)
  • Quotes: Single quotes for strings
  • Semicolons: Required
  • Line Length: Max 100 characters when reasonable

Linting

# Check code style
npm run lint

# Auto-fix style issues
npm run lint -- --fix

Documentation

  • Add JSDoc comments for all exported functions
  • Include descriptions, parameter types, return types, and error conditions
  • Update README.md if adding new features or changing behavior

Example:

/**
 * Converts LCOV coverage data to Coveralls format
 * @param {string} input - LCOV format string or file path
 * @param {Object} options - Configuration options
 * @param {Function} callback - Callback function (err, coverallsData)
 * @throws {Error} If input is invalid or file cannot be read
 */
function convertLcovToCoveralls(input, options, callback) {
  // ...
}

Testing

Running Tests

# Run all tests
npm test

# Run tests with coverage
npm run test-cov

# Run only mocha tests (skip linting)
npm run mocha

# Run tests in watch mode (requires npm install --save-dev mocha)
npx mocha --watch

Writing Tests

  • Place test files in test/ directory
  • Name test files to match source files (e.g., lib/foo.js → test/foo.js)
  • Use the should assertion library (already included)
  • Use proxyquire for mocking modules
  • Aim for 100% code coverage

Example test structure:

'use strict';

const should = require('should');
const proxyquire = require('proxyquire');
const myModule = require('../lib/myModule');

describe('myModule', () => {
  beforeEach(() => {
    // Setup
  });

  afterEach(() => {
    // Cleanup
  });

  it('should do something specific', done => {
    myModule.doSomething((err, result) => {
      should.not.exist(err);
      result.should.equal('expected');
      done();
    });
  });
});

Test Coverage Requirements

  • All new code must have tests
  • Maintain 100% coverage (statements, branches, functions, lines)
  • Run npm run test-cov before submitting PR

Submitting Changes

Before Submitting

  1. Update tests: Add or modify tests for your changes
  2. Run tests: Ensure all tests pass (npm test)
  3. Check coverage: Verify 100% coverage (npm run test-cov)
  4. Lint code: Fix any linting issues (npm run lint)
  5. Update docs: Modify README.md or JSDoc as needed
  6. Commit message: Write clear, descriptive commit messages

Commit Message Format

Use conventional commit format:

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

Example:

feat(retry): add exponential backoff for network failures

Implements retry logic with exponential backoff (max 3 attempts)
for 5xx errors when sending coverage data to Coveralls API.

Closes #123

Pull Request Process

  1. Update your fork:

    git fetch upstream
git checkout master
git merge upstream/master

  2. Create a feature branch:

    git checkout -b feature/my-feature

  3. Make your changes and commit them

  4. Push to your fork:

    git push origin feature/my-feature

  5. Open a Pull Request on GitHub with:

    • Clear title and description
    • Reference any related issues
    • Screenshots/examples if applicable
    • Checklist of changes made

  6. Respond to feedback: Address review comments promptly

Pull Request Checklist

  • Tests added/updated and passing
  • Code coverage maintained at 100%
  • Linting passes without errors
  • Documentation updated (README, JSDoc)
  • Commit messages follow conventional format
  • Branch is up to date with master
  • No merge conflicts

Reporting Issues

Bug Reports

When reporting bugs, please include:

  • Description: Clear description of the issue
  • Steps to Reproduce: Minimal steps to reproduce the problem
  • Expected Behavior: What you expected to happen
  • Actual Behavior: What actually happened
  • Environment:
    • Node.js version (node --version)
    • npm version (npm --version)
    • Operating system
    • CI environment (if applicable)
  • Logs: Relevant error messages or logs
  • Sample Code: Minimal reproducible example if possible

Feature Requests

When requesting features, please include:

  • Description: Clear description of the feature
  • Use Case: Why this feature would be useful
  • Proposed Solution: How you envision it working
  • Alternatives: Other solutions you've considered

Development Tips

Debugging

Enable debug logging:

export NODE_COVERALLS_DEBUG=1
# or
node --inspect bin/coveralls.js

Testing with Real Coverage Data

# Generate coverage for this project
npm run test-cov

# Send to Coveralls (requires COVERALLS_REPO_TOKEN)
cat coverage/lcov.info | node bin/coveralls.js

Working with Git

# Test git-related functionality
node -e "require('./lib/fetchGitData')({head: {id: 'HEAD'}}, console.log)"

Questions?

  • Open an issue for questions about contributing
  • Check existing issues and PRs for similar questions
  • Review the README.md for usage documentation

License

By contributing, you agree that your contributions will be licensed under the project's existing license (BSD-2-Clause).

Thank you for contributing to coveralls-next!