Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
221 lines (150 loc) · 7.47 KB

CONTRIBUTING.md

File metadata and controls

221 lines (150 loc) · 7.47 KB
Raw

Contributing to @node-oauth/oauth2-server

Thank you for your interest in this project and your aims to improving it. This guide will give you the most important info on how to contribute properly in order to get your pull requests accepted.

Disclose security vulnerabilities

First things first: This project has strong security implications, and we appreciate every help to improve security.

However, please read our security policy, before taking actions.

Guiding principles

Before contributing to this project it is important to understand how this project and it's collaborators views itself regarding its scope and purpose.

OAuth2 standard compliance

This project aims full standard compliance. All improvements on functionality, as well as security implications, are done in a way that the standard remains as the highest reference of choice.

If you are not familiar with the OAuth2 standards, please consult at least the following documents:

Extended readings:

Framework-agnostic

Design decisions and implementations are always done with keeping in mind, that there are multiple frameworks out there that use this project.

Development

If you want to fix bugs or add new features, please read this chapter and it's sections carefully!

No PR without issue

Please make sure your commitment will be appreciated by first opening an issue and discuss, whether this is a useful addition to the project.

Work on a bug or a new feature

First, clone and install this project from source via

git clone git@github.com:node-oauth/node-oauth2-server.git
cd node-oauth2-server
npm install

Note: CI runs on Node 24 (npm 11). Use a matching version locally, and regenerate package-lock.json with npm 11 if you change dependencies. Older npm versions rewrite the lock file — dropping the cross-platform optional dependencies that npm ci needs — which breaks CI even when it installs fine on your machine.

From here you can run several scripts for development purposes:

npm run test           # runs the linter, then the tests once
npm run test:coverage  # runs the tests including coverage
npm run lint           # runs the linter
npm run lint:fix       # runs the linter and auto-fixes what it can
npm run docs:api       # regenerates the API docs from JSDoc comments
npm run docs:dev       # serves the documentation site locally

Make sure your master is up to date, then create a branch for your work:

git switch master && git pull
git switch -c feature-xyz # or fix-xyz

Coding rules

  • Unit-testing: all features or bug fixes must be tested by specs
  • Documentation: all public API methods must be documented

Commit message convention

We follow Conventional Commits. Every commit is linted in CI against @commitlint/config-conventional, and releases are produced automatically from the commit history by semantic-release — so the format is required, not just a style preference. Non-conforming commits fail CI.

<type>(<optional scope>): <short summary>

The summary is written in the imperative mood, lower-case, with no trailing period. The <type> and <summary> are mandatory; the (<scope>) is optional.

Release-triggering types — these appear in the changelog and, on merge to master, trigger a release:

  • fix: — patch release
  • feat: — minor release
  • feat!: (or any commit with a BREAKING CHANGE: footer) — major release

Non-release types: docs, test, refactor, perf, style, build, ci, chore.

Do not reference issues or PRs in the commit summary or body — link them from the pull request description instead. References in commit messages get replayed (re-notifying the linked thread) every time history is rebased or squashed.

Run the tests before committing

Please always make sure your code is passing linter and tests before committing. By doing so you help to make reviews much easier and don't pollute the history with commits, that are solely targeting lint fixes.

You can run the tests via

npm run test

or

npm run test:coverage

to see your coverage.

Open a pull request (PR)

Once you have implemented your changes and tested them locally, please open a pull request.

Note: sometimes a pull request (PR) is also referred to as merge request (MR).

Fundamental PR requirements

There are a few basic requirements for your pull request to become accepted:

  • Open your pull request against the master branch
  • Make sure you are working on a dedicated branch, not master; usually you can name the branch after the feature or fix you want to provide
  • Resolve any merge conflicts by keeping your branch up to date with master
  • Have a clear description on what the PR does, including any steps necessary for testing, reviewing, reproduction etc.
  • Link to the existing issue
  • Added functions or changed functions need to get documented in compliance with JSDoc
  • Make sure all CI Tests are passing

Also make sure, to comply with the following list:

  • Do not work on master directly
  • Do not implement multiple features in one pull request (this includes bumping versions of dependencies that are not related to the PR/issue)
  • Do not bump the release version or edit CHANGELOG.md — both are produced automatically by semantic-release when your PR is merged
  • Do not introduce tight dependencies to a certain package that has not been approved during the discussion in the issue

Review process

Finally, your PR needs to pass the review process:

  • A certain amount of maintainers needs to review and accept your PR
  • Please expect change requests! They will occur and are intended to improve the overall code quality.
  • If your changes have been updated please re-assign the reviewer who asked for the changes
  • Once all reviewers have approved your PR it will be merged by one of the maintainers 🎉

After merge

Please delete your branch after merge.

Documentation

We use Vitepress+Markdown for our documentation. If you want to contribute to the docs, please get familiar with Vitepress: https://vitepress.dev

Setting up docs

You need NPM to set up the docs using the following:

npm install
npm run docs:setup

You can then edit the guide section manually.

API Docs

DO NOT edit the api section, as API docs are automatically generated from our internal JSDoc comments.

Instead, update the comments directly within the code and run npm run docs:api to generate the api docs.

Building the docs

Run npm run docs:build to build the docs.