Rules for external contributors

The page describes what you need to do to get your changes accepted into the Diplodoc project.

Code requirements

Code style and linting

Write code in a consistent style. For checking, use the package @diplodoc/lint:

• ESLint — checking JavaScript/TypeScript code.
• Prettier — code formatting.
• Stylelint — checking CSS/SCSS.

Before submitting a pull request, run:

npm run lint

To automatically fix errors:

npm run lint:fix

TypeScript

• Write all source code in TypeScript.
• Extend the shared configuration @diplodoc/infra/tsconfig.json.
• Check types with the command npm run typecheck.

Documenting architectural changes (ADR)

If your changes affect the project's architecture, create an ADR file in Markdown format in the appropriate repository folder. In the file, specify:

• the problem context;
• the considered solution options;
• the accepted decision and its rationale.

Testing

Cover your changes with tests — this is a mandatory condition for accepting a pull request.

Test runner

The project uses Vitest. Other test runners, such as Jest, are not supported.

npm run test        # Running tests
npm run test:watch  # Running in watch mode

Test structure

• Unit tests — place them next to the code being tested:

  • src/**/*.test.ts
  • src/**/*.spec.ts
  • src/**/__tests__/

• Integration tests — in the test/ directory (not tests/):

  • test/**/*.test.ts

Configuration

Create a vitest.config.mjs file in the package root:

import {defineConfig} from 'vitest/config';

export default defineConfig({
    test: {
        include: ['src/**/*.test.ts', 'test/**/*.test.ts'],
        exclude: ['node_modules', 'build'],
    },
});

Pull request requirements

Description of changes

Add to the pull request:

• Problem description — what you are fixing or adding.
• Solution description — how you solved the problem.
• Links — to related issues or documentation.

Commit formatting

For detailed commit formatting requirements, see the section Making changes to the project.

Requirements for Extensions

Using a template

When creating a new extension, use the official template from the package-template repository.

Consideration of multithreading

Documentation builds can run in multithreaded mode. Make sure your extension:

• does not use global state;
• works correctly when executed in parallel;
• does not create race conditions.

Module infrastructure

@diplodoc/lint

Use @diplodoc/lint for a unified linting infrastructure:

# Initializing a new package
npx @diplodoc/lint init

# Updating an existing package
npx @diplodoc/lint update

Scripts in package.json

Define the following scripts in package.json:

Watch mode

The npm run watch command starts the development environment: it builds packages, watches for changes, and automatically restarts the build. This lets you see the result of changes immediately without manually running build commands.

More on GitHub

Module files

Add to each module:

• SECURITY.md — security policy
• CONTRIBUTING.md — contributor guide
• LICENSE — project license
• vitest.config.mjs — Vitest configuration
• .github/workflows/ — CI/CD workflows

GitHub Workflows

Each package must contain standard workflows in the .github/workflows/ directory.

Required workflows:

• tests.yml — main testing workflow (runs lint, typecheck, tests)
• release.yml — release workflow
• release-please.yml — release-please configuration
• package-lock.yml — package lock update
• security.yml — security scanning
• update-deps.yml — dependency update

Special workflows (keep if needed):

• E2E-specific workflows (e.g., diplodoc-e2e-tests.yaml)
• Custom workflows for package-specific needs

Workflows to remove (duplicates):

• tests.yaml (duplicate of tests.yml)

When configuring workflows:

1. Check existing workflows in .github/workflows/.
2. Remove duplicate workflows (.yaml vs .yml).
3. Make sure all standard workflows are present.
4. Keep special workflows if they perform a specific function.
5. Verify the correctness of workflow configuration.

More in the documentation

Unsupported tools

Tools and packages that are not supported in the project. Use the recommended alternatives.

Build

• Webpack → use esbuild
• tsc for building JS → use esbuild, tsc only for declarations

Deprecated packages

• @diplodoc/eslint-config → use @diplodoc/lint
• @diplodoc/prettier-config → use @diplodoc/lint

Checklist before submitting a PR

Before submitting a pull request, check:

• The code follows the project style (npm run lint passes without errors).
• Types are checked (npm run typecheck passes without errors).
• Tests are written and pass (npm run test passes without errors).
• The build works (npm run build passes without errors).
• The pull request contains a description of the changes.
• An ADR has been created for architectural changes.
• Screenshots have been added for visual changes.
• Commits follow conventional commits.
• Only supported tools are used (Vitest, esbuild).

Additional resources

• Requirements for contributing to the metapackage
• Managing metapackages
• Development infrastructure