Contributing to cron-parser

August 1, 2026 · View on GitHub

Thank you for your interest in contributing to cron-parser! This document provides guidelines and information for contributors.

Code of Conduct
Reporting Security Issues
Getting Started
Development Setup
How to Contribute
Pull Request Process
Coding Standards
Testing
Benchmarking
Documentation
Issue Guidelines

Code of Conduct

This project and everyone participating in it are governed by the Code of Conduct. By participating, you are expected to uphold it. Please report unacceptable behavior using the channels listed there.

Reporting Security Issues

Do not open a public issue or pull request for a security vulnerability. Report it privately following the Security Policy.

Getting Started

Fork the repository on GitHub

Clone your fork locally:

git clone https://github.com/your-username/cron-parser.git
cd cron-parser

Add the original repository as upstream:

git remote add upstream https://github.com/harrisiirak/cron-parser.git

Development Setup

Prerequisites

Node.js >= 18
npm (comes with Node.js)

Installation

Install dependencies:
```
npm install
```
Build the project:
```
npm run build
```
Run tests to ensure everything works:
```
npm test
```

Available Scripts

npm run build - Build the TypeScript project
npm run test - Run all tests (lint + type check + unit tests + coverage)
npm run test:unit - Run unit tests only
npm run test:coverage - Run tests with coverage report
npm run lint - Run ESLint
npm run lint:fix - Fix ESLint issues automatically
npm run format - Format code with Prettier
npm run format:check - Check code formatting
npm run bench - Run benchmarks
npm run docs - Generate documentation

How to Contribute

Types of Contributions

Bug fixes - Fix issues in the existing codebase
Features - Add new functionality
Documentation - Improve or add documentation
Code improvements - Refactoring, optimization, code quality
Tests - Add or improve test coverage
Performance - Performance optimizations

Before You Start

Check existing issues to see if your contribution is already being worked on
Create an issue to discuss new features or significant changes
Look for good first issues labeled with good first issue for newcomers

Pull Request Process

Create a feature branch from master:

git checkout -b feature/your-feature-name

Make your changes following the coding standards
Write or update tests for your changes
Run the test suite and ensure all tests pass:
```
npm test
```
Update documentation if needed

Commit your changes with a clear commit message:

git commit -m "feat: add support for new cron expression syntax"

Push to your fork:

git push origin feature/your-feature-name

Create a pull request on GitHub

Pull Request Guidelines

Clear title and description explaining the changes
Reference related issues using keywords like "Fixes #123" or "Closes #456"
Include test coverage for new functionality
Update documentation for user-facing changes
Keep commits atomic - one logical change per commit
Rebase your branch on the latest master before submitting

Commit Message Format

This project follows conventional commits format:

type(scope): short 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, dependency updates

Examples:

feat: add support for timezone in cron expressions
fix: handle edge case in day of week calculation
docs: update README with new examples
test: add coverage for CronDate edge cases

Coding Standards

TypeScript

Use TypeScript for all source code
Enable strict mode - the project uses strict TypeScript settings
Provide proper type annotations for public APIs
Use meaningful variable and function names
Follow existing code patterns and conventions

Code Style

Use Prettier for code formatting (configuration in .prettierrc)
Use ESLint for code linting (configuration in eslint.config.js)
Run npm run format before committing
Fix lint issues with npm run lint:fix

File Organization

Source code: Place in src/ directory
Tests: Place in tests/ directory with .test.ts extension
Exports: Update src/index.ts for public API changes
Types: Define types in appropriate files, shared types in src/fields/types.ts

Testing

Unit Tests

Write tests for all new functionality
Use Jest as the testing framework
Place tests in the tests/ directory
Follow the naming convention: ComponentName.test.ts
Maintain high test coverage

Test Structure

describe('ComponentName', () => {
  describe('methodName', () => {
    it('should handle normal case', () => {
      // Arrange
      const input = 'test input';

      // Act
      const result = component.method(input);

      // Assert
      expect(result).toBe(expectedOutput);
    });

    it('should throw error for invalid input', () => {
      expect(() => component.method(invalidInput)).toThrow('Expected error message');
    });
  });
});

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:unit -- --watch

# Run specific test file
npm run test:unit -- CronExpression.test.ts

# Run tests with coverage
npm run test:coverage

Benchmarking

The project includes benchmarking tools to measure performance:

# Run benchmarks
npm run bench

# Run pattern-specific benchmarks
npm run bench:pattern

# Clean benchmark results
npm run bench:clean

The run can be tuned with environment variables:

# Compare against a specific published version instead of the latest release
PACKAGE_VERSION=5.6.2 npm run bench

# Shorten a run while iterating (defaults: 10000 iterations, 5 samples)
BENCHMARK_ITERATIONS=100 BENCHMARK_SAMPLES=1 npm run bench