Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
88 lines (55 loc) · 3.58 KB

CONTRIBUTING.md

File metadata and controls

88 lines (55 loc) · 3.58 KB

Contributing to the npm API documentation

This is the documentation for https://api-docs.npmjs.com/. Do you want to contribute a change? Great!

Read through our contributing guidelines below to get started.

Table of Contents

Quick Start

Ready to contribute to the npm API documentation? Here's how to get started:

  1. Install dependencies: npm install
  2. Update the documentation - it's OpenAPI YAML format - in the api/ directory:
  3. Test your changes: npm run build (generates index.html and openapi.yaml)
  4. Review your changes: Inspect the generated html/index.html file in your browser or check the openapi.yaml file for your changes
  5. Fix any issues: npm run lintfix:yaml for YAML formatting
  6. Submit your PR: Commit your changes and open a pull request at https://github.com/npm/api-documentation

Code of Conduct

All interactions in the npm organization on GitHub are considered to be covered by our standard Code of Conduct.

Reporting Bugs

Before submitting a new bug report please search for an existing or similar report.

Use one of our existing issue templates if you believe you've come across a unique problem.

Duplicate issues, or issues that don't use one of our templates may get closed without a response.

Pull Request Conventions

Commits

We use Conventional Commits.

When opening a pull request please be sure that either the pull request title, or each commit in the pull request, has one of the following prefixes:

  • feat: For when introducing a new feature, such as a new subdomain.
  • fix: For bug fixes.
  • docs: For documentation updates.
  • chore: For changes that do not affect the published page. Often these are changes to deployment workflows.

Linting

This project validates both YAML documentation and JavaScript code. To check for linting errors, run:

npm run generate && npm run validate

This will:

  1. Generate the merged OpenAPI specification from source files
  2. Validate the OpenAPI specification using Redocly CLI

For fixing linting errors:

  • YAML/Documentation errors: Run npm run lintfix:yaml (uses Prettier for formatting)
  • JavaScript errors: Run npm run lintfix:js (uses ESLint auto-fix)

Please make sure all linting passes before submitting a PR.

What not to contribute?

Dependencies

It should be noted that our team does not accept third-party dependency updates/PRs. If you submit a PR trying to update our dependencies we will close it with or without a reference to these contribution guidelines.

Tools/Automation

Our core team is responsible for the maintenance of the tooling/automation in this project and we ask contributors to not make changes to these when contributing (e.g. .github/*, .eslintrc.json, .licensee.json). Most of those files also have a header at the top to remind folks they are automatically generated. Pull requests that alter these will not be accepted.