Skip to content

Latest commit

 

History

History
152 lines (107 loc) · 5.68 KB

CONTRIBUTING.md

File metadata and controls

152 lines (107 loc) · 5.68 KB

Contributing

From opening an issue for a documentation suggestion to creating a pull request: every contribution is appreciated and welcome. If you're planning to implement a new section or page please create an issue first.

Setup

Start by ensuring that you have Node.js installed and forking the repository:

  • Install Node.js if you have not already.
  • Install Yarn if you have not already. Yarn is an alternative to npm, and it is required for building the site as we use yarn specific features like resolutions which are not available in other package managers like pnpm.
  • Fork the webpack.js.org repo from the main repository.
  • git clone <your-clone-url> && cd webpack.js.org

To run the project, you must run scripts that download the website content from GitHub. To avoid hitting rate limits, you'll need to use your GitHub token. The build scripts (fetch-repo and fetch:* commands) use this token to retrieve repository data, including documentation, examples, and contributors. If you do not have one, you can create it on the GitHub Personal Access Tokens page.

Once you are in the project directory, run the following commands:

  • yarn to pull all dependencies.
  • GITHUB_TOKEN=<your-token-here> yarn fetch-all - Fetches all updated website content from GitHub.
  • yarn build to create a production version of the site.
  • yarn start to develop on a local webpack-dev-server: localhost:3000.

Note: The fetch and fetch-repos commands must be run before building the site as they populate necessary data for the build process.

NOTE: run yarn fetch-repos and then yarn fetch before running yarn start command for the first time

  • yarn fetch to retrieve external documentation/data.

The final command, yarn fetch, is optional as both yarn build and yarn start will do this automatically. This step pulls in documentation for loaders/plugins hosted in separate repositories such as the ones found in the webpack-contrib organization. See the package.json for the full list of scripts.

Note

Node v20.9.0 or above is required for the build process to run properly.

Contributor License Agreement

When submitting your contribution, a CLA (Contributor License Agreement) bot will come by to verify that you signed the CLA. If it is your first time, it will link you to the right place to sign it. However, if you have committed your contributions using an email that is not the same as your email used on GitHub, the CLA bot can't accept your contribution.

Run git config user.email to see your Git email, and verify it with your GitHub email.

Editor Config

The .editorconfig in the root should ensure consistent formatting. Please make sure you've installed the plugin if your text editor needs one.

Testing

Run the full test suite (lint + Jest) with:

yarn test

To run only Jest tests:

yarn jest

To update snapshots after intentional UI changes:

NODE_OPTIONS=--experimental-vm-modules jest --config=jest.config.mjs --updateSnapshot

Branching Your Changes

Making a branch in your fork for your contribution is helpful in the following ways:

  • It allows you to have multiple contributions in as PRs at once.
  • It allows us to identify what your contribution is about from the branch name.

Committing Your Changes

Please follow the conventional commits specification. For example, for documentation changes, a short commit message may resemble the following:

docs(config): clarify `output.filename` usage

Note that you can add a body/footer if more details are necessary. Soon we will start utilizing standard-version for releases/changelog generation. This will also potentially tie in to having archived docs for each major version.

Submitting Changes

After getting some feedback, push to your fork branch and submit a pull request. We may suggest some changes or improvements or alternatives, but for small changes your pull request should be accepted and merged fairly quick.

Before submitting a pull request, ensure your feature branch is up to date with the latest changes from the upstream main branch to avoid conflicts during review. You can go through this article to learn about rebase technique

Issue the PR to the main branch.

See GitHub documentation for more help.

Recognition

You can choose to add your GitHub username for recognition at the top of any markdown document you edit:

example.md

---
title: Some Example Page
contributors:
  - TheLarkInn
  - Sokra
  - bebraw
  - Jhnns
  - SpaceK33z
---

Some documentation...

This will add your name and GitHub profile photo to the document in production. It's a great way to own the awesome work that you do and we encourage you to do this in your PRs.

Thank You

Webpack is a feature rich, low level tool and documentation is a huge time sink. We appreciate any time spent fixing typos or clarifying sections in the documentation.