Skip to content

chore(docs): update CONTRIBUTING.md with additional information #310

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jun 5, 2025
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
240 changes: 203 additions & 37 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,98 +1,264 @@
# # Node.js `api-docs-tooling` Contributing Guide
# Node.js `api-docs-tooling` Contributing Guide

Thank you for your interest in contributing to the Node.js `api-docs-tooling` project! We welcome contributions from everyone, and we appreciate your help in making this project better.

## Getting started
## Table of Contents

The steps below will give you a general idea of how to prepare your local environment for the Node.js Website and general steps
for getting things done and landing your contribution.
- [Getting Started](#getting-started)
- [Prerequisites](#prerequisites)
- [Setting Up Your Development Environment](#setting-up-your-development-environment)
- [Development Workflow](#development-workflow)
- [Making Changes](#making-changes)
- [Submitting Your Changes](#submitting-your-changes)
- [Writing Tests](#writing-tests)
- [Test File Organization](#test-file-organization)
- [Writing Test Code](#writing-test-code)
- [Use Node.js Built-in Test Runner](#use-nodejs-built-in-test-runner)
- [Test Structure](#test-structure)
- [Best Practices](#best-practices)
- [Example Test File](#example-test-file)
- [Running Tests](#running-tests)
- [Code Quality](#code-quality)
- [Linting and Formatting](#linting-and-formatting)
- [Pre-commit Hooks](#pre-commit-hooks)
- [Commit Guidelines](#commit-guidelines)
- [Developer's Certificate of Origin 1.1](#developers-certificate-of-origin-11)

1. Click the fork button in the top right to clone the [Node.js `api-docs-tooling` Repository](https://github.com/nodejs/api-docs-tooling/fork)
## Getting Started

2. Clone your fork using SSH, GitHub CLI, or HTTPS.
The steps below will give you a general idea of how to prepare your local environment for the Node.js `api-docs-tooling` project and general steps for getting things done and landing your contribution.

### Prerequisites

- Node.js (latest LTS version, check the [`.nvmrc` file](/.nvmrc))
- [Git][]
- A GitHub account

### Setting Up Your Development Environment

1. **Fork the repository**

Click the fork button in the top right, or the link in this paragraph, to clone the [Node.js `api-docs-tooling` Repository](https://github.com/nodejs/api-docs-tooling/fork)

2. **Clone your fork**

```bash
git clone [email protected]:<YOUR_GITHUB_USERNAME>/api-docs-tooling.git # SSH
git clone https://github.com/<YOUR_GITHUB_USERNAME>/api-docs-tooling.git # HTTPS
gh repo clone <YOUR_GITHUB_USERNAME>/api-docs-tooling # GitHub CLI
```

3. Change into the `api-docs-tooling` directory.
3. **Navigate to the project directory**

```bash
cd api-docs-tooling
```

4. Create a remote to keep your fork and local clone up-to-date.
4. **Set up upstream remote**

```bash
git remote add upstream [email protected]:nodejs/api-docs-tooling # SSH
git remote add upstream https://github.com/nodejs/api-docs-tooling # HTTPS
gh repo sync nodejs/api-docs-tooling # GitHub CLI
```

5. Create a new branch for your work.
5. **Install dependencies**

```bash
git checkout -b <name-of-your-branch>
npm install
```

6. Run the following to install the dependencies.
## Development Workflow

### Making Changes

1. **Create a new branch for your work**

```bash
npm install
git checkout -b <name-of-your-branch>
```

7. Perform your changes.
2. **Perform your changes**

8. Perform a merge to sync your current branch with the upstream branch.
Make your code changes, add features, fix bugs, or improve documentation.

3. **Keep your branch up-to-date**

```bash
git fetch upstream
git merge upstream/main
```

9. Run `node --run format` and `node --run lint` to confirm that linting and formatting are passing.
4. **Test your changes**

```bash
node --run format
node --run lint
node --run test
node --run test:coverage # To check code coverage
```

10. Once you're happy with your changes, add and commit them to your branch, then push the branch to your fork.
5. **Check code quality**

```bash
cd ~/api-docs-tooling
git add .
git commit -m "describe your changes"
git push -u origin name-of-your-branch
```
```bash
node --run format
node --run lint
```

> [!IMPORTANT]\
> Before committing and opening a Pull Request, please go first through our [Commit](#commit-guidelines);
### Submitting Your Changes

11. Create a Pull Request.
1. **Add and commit your changes**

## Commit Guidelines
```bash
git add .
git commit -m "describe your changes"
```

This project follows the [Conventional Commits][] specification.
2. **Push to your fork**

```bash
git push -u origin <name-of-your-branch>
```

3. **Create a Pull Request**

Go to your fork on GitHub and create a Pull Request to the main repository.

> [!IMPORTANT]
> Before committing and opening a Pull Request, please go through our [Commit Guidelines](#commit-guidelines) and ensure your code passes all tests and quality checks.

## Writing Tests

Testing is a crucial part of maintaining code quality and ensuring reliability. All contributions should include appropriate tests.

### Test Coverage

- **Patches (PRs) are required to maintain 80% coverage minimum**
- **Contributors are encouraged to strive for 95-100% coverage**
- New features and bug fixes should include corresponding tests
- Tests should cover both happy path and edge cases

### Commit Message Guidelines
### Test File Organization

- Commit messages must include a "type" as described on Conventional Commits
- Commit messages **must** start with a capital letter
- Commit messages **must not** end with a period `.`
Tests should be organized to mirror the source code structure:

- For a source file at `/src/index.mjs`, create a test file at `/src/__tests__/index.test.mjs`
- For a source file at `/src/utils/parser.mjs`, create a test file at `/src/utils/__tests__/parser.test.mjs`
- Test files should use the `.test.mjs` extension

- For a fixture used in `/src/__tests__/some.test.mjs`, place the fixture at `/src/__tests__/fixtures/some-fixture.mjs`.
- When fixtures are used in multiple tests, place them in the test directory of the closest shared ancestor. For instance, if a fixture is used by both `/src/__tests__/some.test.mjs`, and `/src/utils/__tests__/parser.test.mjs`, the fixture belongs in `/src/__tests__/fixtures/`.

### Writing Test Code

Tests should follow these guidelines:

#### Use Node.js Built-in Test Runner

```javascript
import assert from 'node:assert/strict';
import { describe, it } from 'node:test';
```

#### Test Structure

Use `describe` and `it` syntax for organizing tests:

```javascript
describe('MyModule', () => {
describe('myFunction', () => {
it('should return expected result for valid input', () => {
// Test implementation
assert.strictEqual(actual, expected);
});

it('should throw error for invalid input', () => {
assert.throws(() => {
// Code that should throw
});
});
});
});
```

#### Best Practices

- **Use strict assertions**: Always use `node:assert/strict` over `node:assert`.
- **Focused testing**: Tests should ideally only test the specific file they are intended for
- **Use mocking**: Mock external dependencies to isolate the code under test
- **Code splitting**: Encourage breaking down complex functionality for easier testing

#### Example Test File

```javascript
// tests/index.test.mjs
import assert from 'node:assert/strict';
import { describe, it } from 'node:test';

import { myFunction } from '../index.mjs';

describe('index.mjs', () => {
describe('myFunction', () => {
it('should process valid input correctly', () => {
const input = 'test input';
const result = myFunction(input);
assert.strictEqual(result, 'expected output');
});

it('should handle edge cases', () => {
assert.strictEqual(myFunction(''), '');
assert.strictEqual(myFunction(null), null);
});

it('should throw for invalid input', () => {
assert.throws(() => myFunction(undefined), {
name: 'TypeError',
message: 'Input cannot be undefined',
});
});
});
});
```

### Running Tests

```bash
# Run all tests
node --run test

# Run tests with coverage
node --run test:coverage

# Run specific test file
node --test src/test/index.test.mjs
```

## Code Quality

### Linting and Formatting

This project uses automated code quality tools:

```bash
# Format code
node --run format # To apply changes, use `format:write`

# Lint code
node --run lint # To apply changes, use `lint:fix`
```

### Pre-commit Hooks

This project uses [Husky][] for Git pre-commit hooks.
It's lint and format stages your code before committing.
You can disable the pre-commit hooks by using the `--no-verify` flag.
This project uses [Husky][] for Git pre-commit hooks that automatically lint and format your code before committing.

You can bypass pre-commit hooks if necessary (not recommended):

```bash
git commit -m "describe your changes" --no-verify
```

## Commit Guidelines

This project follows the [Conventional Commits][] specification.

## Developer's Certificate of Origin 1.1

```
Expand All @@ -114,5 +280,5 @@ By contributing to this project, I certify that:
```

[Conventional Commits]: https://www.conventionalcommits.org/
[Commit Signing]: https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits
[Git]: https://git-scm.com/downloads
[Husky]: https://typicode.github.io/husky/
Loading