Skip to content

Latest commit

 

History

History
135 lines (84 loc) · 7.94 KB

CONTRIBUTING.md

File metadata and controls

135 lines (84 loc) · 7.94 KB
Raw

Contributing

Welcome, we really appreciate if you're considering to contribute, the joint effort of our contributors make projects like this possible!

The goal of this document is to provide guidance on how you can get involved.

Asking questions

Have a question or feature request? Rather than opening an issue, use the Discussions board.

Please be polite and take the time to write a well-worded question so our community members can easily assist you.

Prerequisites

Before starting make sure you have the following installed:

Getting started

In order to make it easier to get familiar with the codebase we labeled simpler issues using Good First Issue and Help Wanted. You can learn the internals by reading the documentation or by starting from packages/core/core/src/Parcel.js

Pull requests

For significant changes, it is recommended that you first propose your solution and gather feedback.

Before submitting a pull request, you can follow this step by step guide:

  1. Fork the repository and setup a new branch to work in.

It's important that the changes are made in separate branches to ensure a pull request only includes the commits related to a bug or feature.

  1. Run yarn and yarn build-native in the repository root to install dependencies.
  2. If you fix a bug or introduce a new feature, add tests or ask for help if the use-case is more complex.
  3. Commit the yarn.lock file if it has changed.
  4. Check the steps used in ci pass locally.
$ yarn build-ts
$ yarn flow check
$ yarn lint
$ yarn test

⚠️ Don't modify the package.json versioning

Once you are ready to create a pull request, provide relevant details about the change; examples; and test cases. All submissions require review, so please be patient!

Development workflow

The following commands are available:

  • yarn build-ts generates the TypeScript type definitions.
  • yarn flow check runs the Flow type checking.
  • yarn format keeps the code formatting consistent.
  • yarn lint checks for stylistic or unwanted errors.
  • yarn test runs all the unit and integration tests.
  • yarn test:integration runs the integration tests.
  • yarn test:unit runs the unit tests.

Debugging

Both VSCode and CLion can be used to debug commands such as the integration test suite.

  • CLion is well supported, using default configurations for the relevant language.
  • VSCode users can use the JavaScript Debug Terminal or Node.js launch configuration to debug JavaScript. Rust debugging requires a LLDB powered launch configuration, which is available by installing the CodeLLDB extension.

Breakpoints not triggering? Try passing in PARCEL_WORKERS=0 to make all code run on the main thread, instead of in worker processes. Similarly, you can set PARCEL_MAX_CONCURRENT_CALLS to change the limit of concurrent calls per worker.

Plugins

When developing plugins, you should disable caching with the --no-cache CLI or shouldDisableCache: true Parcel option. This will ensure you do not see stale or incomplete results.

Working from an example

Please don't commit these examples.

You can create a temporary example for debugging in the folder packages/examples. Start by copying the simple example and try to reproduce the bug. It has everything setup for working on local changes and you can run yarn build to build the project. If you're re-using another example or creating one from scratch, make sure to use the --no-cache flag for parcel build to see your local changes reflected.

Testing outside of the monorepo

You can run /path/to/monorepo/packages/core/parcel/src/bin.js build src/index.html provided that you don't have any @parcel/* plugins installed in this project.

Releasing a new version

When releasing a new version of Parcel a couple steps should be followed:

  1. Run yarn tag:prerelease 2.0.0-alpha.1 or yarn tag:release 2.4.5 based on whether it is a prerelease (alpha, beta, nightly, ...) or a stable release
  2. Open a PR (or commit directly to the default branch)
  3. Wait for the PR to get merged
  4. Create a GitHub release and publish it (this should automatically trigger an npm release, with the current state of the default branch and versions defined in the package.json files)

After these steps are completed there should be a new version of Parcel published on npm.

In case the automatic npm release failed, or you want to do a manual release for any other reason you can also run yarn run release

Become a backer or sponsor

Showing appreciation makes us happy, donations help us grow.

Our financial situation is fully transparent on our open collective.

Anyone can file an expense. If the expense makes sense for the development of the community, it will be "merged" in the ledger of our open collective by the core contributors and the person who filed the expense will be reimbursed.

Credits

Contributors

Thank you to all the people who have already contributed to parcel!

Backers

Thank you to all our backers! [Become a backer]

Sponsors

Thank you to all our sponsors! (please ask your company to also support this open source project by becoming a sponsor)