Skip to content

Latest commit

 

History

History
199 lines (143 loc) · 9.55 KB

CONTRIBUTING.md

File metadata and controls

199 lines (143 loc) · 9.55 KB
Raw

Node.js Website Contributing Guide

Thank you for your interest in contributing to the Node.js Website. Before you proceed, briefly go through the following:

Getting started

  1. Click the fork button in the top right to clone the nodejs.org repository

  2. Clone your fork using SSH, GitHub CLI, or HTTPS.

git clone [email protected]:<GITHUB_ID>/nodejs.org.git # SSH
git clone https://github.com/<GITHUB_ID>/nodejs.org.git # HTTPS
gh repo clone <GITHUB_ID>/nodejs.org # GitHub CLI
  1. Change into the nodejs.org directory.
cd nodejs.org
  1. Create a remote for keeping your fork as well as your local clone up-to-date.
git remote add upstream [email protected]:nodejs/nodejs.org.git # SSH
git remote add upstream https://github.com/nodejs/nodejs.org.git # HTTPS
gh repo sync nodejs/nodejs.org # GitHub CLI
  1. Create a new branch for your work.
git checkout -b name-of-your-branch
  1. Run the following to install the dependencies and start a local preview of your work.
npm ci # installs this project's dependencies
npx turbo serve # starts a preview of your local changes
  1. Perform a merge to sync your current branch with the upstream branch.
git fetch upstream
git merge upstream/main
  1. Run npx turbo format to confirm that linting, and formatting are passing.
npx turbo format

  1. Once you're happy with your changes, add and commit them to your branch, then push the branch to your fork.

    ```bash
cd ~/nodejs.org
git add .
git commit -m "some message"
git push -u origin name-of-your-branch
```

  2. Create a Pull Request. See PR Policy

Note: Go through our Commit and Pull Request guidelines outlined below.

CLI Options

Serve/Build Options

  • npx turbo serve runs Next.js's Local Development Server, listening by default on http://localhost:3000/.
  • npx turbo build builds the Application on Production mode. The output is by default within .next folder.
    • This is used for the Node.js Vercel Deployments (Preview & Production)
  • npx turbo deploy builds the Application on Export Production Mode. The output is by default within build folder.
    • This is used for the Node.js Legacy Website Server (DigitalOcean)
  • npx turbo start starts a web server running serving the built content from npx turbo build

Other CLI options

We also offer other commands that offer you assistance during your local development

  • npx turbo lint runs the linter for all the js files.
    • npx turbo lint:fix attempts to fix any linting errors
  • npx turbo prettier runs the prettier for all the js files.
    • npx turbo prettier:fix attempts to fix any style errors
  • npx turbo format formats and fixes the whole codebase
  • npx turbo scripts:release-post generates a release post for the current release
    • Usage: npx turbo scripts:release-post -- --version=vXX.X.X --force
  • npx turbo storybook starts Storybook's local server
  • npx turbo storybook:build builds Storybook as a static web application for publishing
  • npx turbo test runs all tests locally
    • npx turbo test:unit runs jest (unit-tests) locally
    • npx turbo test:storybook runs storybook test-runner tests
      • npx turbo test:storybook:snapshot generates and updates snapshots for all storybook components.

Vocabulary

  • A Contributor is any individual who creates an issue/PR, comments on an issue/PR or contributes in some other way.
  • A Collaborator is a contributor with write access to the repository. See here on how to become a collaborator.

Standards for making code changes

Refer to the Collaborator Guide for guidelines on code writing and editing.

Commit Guidelines

This project follows the Conventional Commits specification.

Commits should be signed. You can read more about Commit Signing here.

Commit Message guidelines

  • Commit messages must include a "type"

    build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test

  • Commit messages must start with a capital letter
  • Commit messages must not end with a period .

Pull Request Policy

Before merging

We recommend a read on our Collaborator Guide for in-depth details on how we accept contributions into this repository. The list below describes some of the merging and approval rules adopted in this repository.

  • Pull Requests must be open for at least 48 hours (Or 72 hours if the PR was authored on the weekend).
    • Pull requests might be immediately merged if they contain critical bug fixes, short erratas (e.g. typos from previous PRs) or any critical change that is considered a "showstopper" for the operation of the website.
      • These kind of PRs should only be done by existing collaborators that have write-access and/or signed-off by administrators/maintainers.
      • This rule cannot be used for updates on the COLLABORATOR_GUIDE, CONTRIBUTING guide, CODEOWNERS, GitHub Actions or any security-impacting file or document that changes the governing policies of this repository.
    • Pull requests might be "fast-tracked", which means, they can be merged before the usual 48 hours notice if a "fast-track" label is added.
      • The person that is fast-tracking the PR (adding the label) must also comment on the PR that they're requesting the PR to be fast-tracked
      • The comment must mention @nodejs/website and must have at least one 👍 (or any other sort of approval reaction) if the person fast-tracking the PR is the author of the PR.
      • Fast-tracking is only allowed for small bug fixes, small feature changes, localisation changes, or other sort of non-critical/highly-impacting changes that are not covered by the previous rule that allows PRs to be merged immediately.
      • Fast-tracking cannot be used for updates on the COLLABORATOR_GUIDE, CONTRIBUTING guide, CODEOWNERS, GitHub Actions or any security-impacting file or document that changes the governing policies of this repository.
  • There must be no objections after a 48 hour period (Or 72 hours if the PR was authored on the weekend).
  • At least two approvals are required if the target branch is main
  • Tests must be included in Pull Requests for new features or bug fixes. If any test(s) are failing, you are responsible for fixing them.

Each contribution is accepted only if there is no objection to it by a collaborator. During the review, collaborators may request that a specific contributor who is an expert in a particular area give an "LGTM" before the PR can be merged.

In the case that an objection is raised in a pull request by another collaborator, all collaborators involved should try to arrive at a consensus by addressing the concerns through discussion, compromise, or withdrawal of the proposed change(s).

When merging

  • squash pull requests made up of multiple commits

Becoming a collaborator

  • Collaborators must be actively contributing to the project
  • A Pull Request must be opened on the @nodejs/nodejs.org README file adding the new collaborator to the list (note the order of names)
  • The Pull Request must be approved by at least two members of @nodejs/website or @nodejs/tsc
  • The Pull Request must remain open for 72 hours without any objections

More details about Collaboration can be found in the COLLABORATOR_GUIDE.md.

Developer's Certificate of Origin 1.1


By contributing to this project, I certify that:

- (a) The contribution was created in whole or in part by me and I have the right to
  submit it under the open source license indicated in the file; or
- (b) The contribution is based upon previous work that, to the best of my knowledge,
  is covered under an appropriate open source license and I have the right under that
  license to submit that work with modifications, whether created in whole or in part
  by me, under the same open source license (unless I am permitted to submit under a
  different license), as indicated in the file; or
- (c) The contribution was provided directly to me by some other person who certified
  (a), (b) or (c) and I have not modified it.
- (d) I understand and agree that this project and the contribution are public and that
  a record of the contribution (including all personal information I submit with it,
  including my sign-off) is maintained indefinitely and may be redistributed consistent
  with this project or the open source license(s) involved.

Remarks

If something is missing here, or you feel something is not well described, feel free to open an issue to discuss it.