Contributing

Before You Start

• Search Existing Issues & Discussions: Before creating a new issue or discussion, please check the existing GitHub Issues and GitHub Discussions to prevent duplicates.
• AI Usage Policy: Using AI tools (e.g., ChatGPT, GitHub Copilot) to help write code or documentation is fine, provided that you carefully verify, test, and take ownership of all submitted changes.
• Create issue for your PR: Ensure that there is an active issue in the issues tab for your PR and the same is linked properly. If no issue is there, ensure to create one, this helps in properly tracking the PR to an active issue.

Environment & Local Setup

Prerequisites

• Node.js: v22 (Recommended / Required version)
• pnpm: Our preferred package manager (pnpm v11+)

Setting up Node JS with PNPM

# Download and install latest nvm:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh | bash

# in lieu of restarting the shell
\. "$HOME/.nvm/nvm.sh"

# Download and install Node.js:
nvm install 22

# Verify the Node.js version:
node -v # Should print "v22.x.x".

# Download and install pnpm:
corepack enable pnpm

# Verify pnpm version:
pnpm -v

Setting Up the Project (Forking & Cloning)

git clone https://github.com/YOUR-USERNAME/multiple-cucumber-html-reporter.git

cd multiple-cucumber-html-reporter

git remote add upstream https://github.com/WasiqB/multiple-cucumber-html-reporter.git

pnpm install

pnpm build

pnpm link --global ./reporter

pnpm install

Pre-commit Git Hooks (Linting & Formatting)

This repository uses Husky and lint-staged to run pre-commit checks automatically.

• Every time you execute git commit, lint-staged automatically formats and lints your staged TypeScript and JSON files using Biome (pnpm format:fix, pnpm lint:fix).
• Commit message linting (commitlint) is also enforced on pre-commit to maintain Conventional Commit history.

Recommended IDE Setup

• Editor: We recommend using VS Code.
• Extensions: Install the Biome VS Code extension (biomejs.biome) for consistent code formatting and linting directly inside your editor.

Project Structure

Understanding the workspace organization:

multiple-cucumber-html-reporter/
├── .github/          # GitHub Actions workflows and templates
├── docs/             # Documentation site (Fumadocs / Next.js)
│   └── content/docs/
│       ├── (beta)/   # Documentation for upcoming / unreleased beta features
│       └── latest/   # Documentation for stable releases
├── examples/         # Sample projects for debugging & manual testing
└── reporter/         # Core reporter package source code

Development & Debugging

Debugging with Sample Projects

To test and debug your changes against realistic setups, utilize the sample projects in the examples/ directory:

1. Build / link the core package if necessary.
2. Navigate to one of the example directories under examples/.
3. Run the example test scripts by running pnpm test.
4. Run the command mchr or pnpm report to generate and view the report.

Running Test Suite

To verify your changes, run the following command from the reporter folder:

# Run unit tests
pnpm test

# Run test coverage report
pnpm unit.test.coverage

Updating GitHub Workflows

Update files under .github/workflows/ only when:

• Adding or modifying CI/CD automation steps.
• Updating matrix test configurations (e.g., Node version matrix).
• Adjusting release, lint, or test workflow triggers.

Updating Documentation

When adding new features, fixing bugs, or changing APIs, update the docs in docs/content/docs/:

• docs/content/docs/(beta)/: Add or update documentation for upcoming / beta features.
• docs/content/docs/latest/: Update documentation applicable to current stable releases.

Building the documentation site

Run the following command from the docs folder in the repository:

pnpm build

Run the local dev server

Run the command:

pnpm dev

Commits & GPG Signing

Commit Message Format

We strictly follow Conventional Commits format enforced via commitlint.

Example:

feat: add support for custom execution metrics

GPG Signed Commits

All commits must be GPG signed for security and verification:

1. Set up a GPG key in Git following GitHub's Managing commit signature verification guide.
2. Ensure commit signing is enabled:

git config --global user.signingkey <YOUR_KEY_ID>
git config --global commit.gpgsign true

Submitting a Pull Request (PR)

git checkout main
git fetch upstream
git merge upstream/main

git checkout -b feat/my-awesome-feature

git push origin feat/my-awesome-feature