Contributing Guidelines

Relevant source files

The following files were used as context for generating this wiki page:

• CONTRIBUTING.md
• package.json
• eslint.config.js
• biome.json
• SECURITY.md
• INCIDENT_RESPONSE.md
• THREAT_MODEL.md

Cheerio welcomes contributions from the community to maintain its position as a fast, flexible, and elegant library for parsing HTML and XML. These guidelines outline the technical expectations, development workflow, and coding standards required for successful integration into the project.

The scope of contribution includes core library features, documentation updates, and ecosystem packages such as htmlparser2 and css-select. Contributors are expected to follow established patterns for API consistency with jQuery while adhering to Cheerio-specific implementation details.

Sources: CONTRIBUTING.md:1-5, INCIDENT_RESPONSE.md:3-5

Development Workflow

The project follows a standard GitHub-based contribution flow. All changes should originate from an issue discussion to ensure the contribution aligns with the project goals.

Step-by-Step Contribution Process

This diagram represents the lifecycle of a contribution from inception to merging.
Sources: CONTRIBUTING.md:6-19

Branching and Commits

• Base Branch: All development branches must be based off the main branch.
• Commit Messages: Messages should describe the approach with sufficient detail to explain technical decisions.
• Pull Requests: Pull requests must reference the initial GitHub issue in the message.

Sources: CONTRIBUTING.md:9-19

Technical Standards and Tooling

Cheerio utilizes a robust toolchain for linting, formatting, and testing to ensure code quality and consistency.

Build and Test Commands

The project uses npm for lifecycle management. Key scripts defined in package.json include:

Command	Description
npm run build	Compiles the project using tshy.
npm run test	Runs the full suite including linting and vitest.
npm run format	Runs both ESLint and Biome formatters.
npm run lint	Checks code against ESLint, Biome, and TypeScript compiler rules.

Sources: package.json:96-107

Quality Control Tools

• ESLint: Configured via eslint.config.js to enforce JavaScript and TypeScript rules, including specific jsdoc and unicorn plugins.
• Biome: Used for fast linting and formatting, configured in biome.json.
• Husky: Manages git hooks to ensure commit hooks are run, enforcing style before code is committed.
• Vitest: The primary testing framework for unit and integration tests.

Sources: eslint.config.js:1-10, biome.json:1-10, package.json:107-130

Code Style and Implementation

Contributors must adhere to specific architectural patterns when implementing new functionality.

Method Conventions

Cheerio differentiates between functionality that requires an instance and functionality that does not.

• Static Methods: Define a named function within the required module if no Cheerio instance reference is needed.
• Instance Methods: For methods requiring this context:
  • Define on the Cheerio.prototype.
  • Prefix private methods with an underscore (_).
  • Include @api private in JSDoc comments.

Sources: CONTRIBUTING.md:27-38

Architectural Constraints

Implementation should consider the library's design:

• this binding: Most methods in src/api are called with the Cheerio instance as this and mixed onto the prototype via Object.assign.
• Private Fields: The project avoids #private class fields for _root, _make, _parse, and _render as they are documented internal APIs.
• Type Coercion: APIs must handle cases where JavaScript callers pass numbers to string-typed parameters (e.g., .attr('width', 100)).

Sources: eslint.config.js:70-76, eslint.config.js:83-85, eslint.config.js:106-112

Documentation Requirements

Any API changes must be reflected in the project's README.md.

• Consistency: Documentation should reuse jQuery's documentation where applicable.
• Distinctness: Clearly note where Cheerio deviates from standard jQuery behavior.
• Website: The website is built with Astro/Docusaurus and requires documentation in Markdown format.

Sources: CONTRIBUTING.md:21-25, website/package.json:7-16

Security and Vulnerability Reporting

Security is a critical component of the contribution process. Cheerio defines strict boundaries for what constitutes a vulnerability.

Reporting Procedure

Do NOT open public issues for security vulnerabilities. Reports must be sent through:

1. Tidelift security contact
2. GitHub private vulnerability reporting

Sources: SECURITY.md:11-17

Severity and Response

Incidents are triaged based on impact and exploitability.

Severity	Target Fix	Update Cadence
Critical	< 7 days	Daily
High	< 14 days	Every 3 days
Medium	Next release	Weekly
Low	Scheduled	As needed

Sources: INCIDENT_RESPONSE.md:15-20

Threat Model Boundaries

• In-Scope: Denial of Service (ReDoS), Prototype Pollution, unexpected code execution, and XSS enablement via incorrect escaping.
• Out-of-Scope: Unsafe use of Cheerio output by the application, malicious transitive dependencies outside the ecosystem, and resource exhaustion from legitimate large inputs.

Sources: THREAT_MODEL.md:29-59

Contributing to Cheerio requires a balance of adhering to proven jQuery syntax while maintaining high performance through strict linting, comprehensive testing, and adherence to the project's security and architectural standards. By following these guidelines, contributors help ensure the project remains the standard for server-side HTML manipulation in Node.js.