You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: CONTRIBUTING.md
+51-28
Original file line number
Diff line number
Diff line change
@@ -10,57 +10,80 @@ Have a question or feature request? Rather than opening an issue, use the [Discu
10
10
11
11
Please be polite and take the time to write a well-worded question so our community members can easily assist you.
12
12
13
-
## Getting started with bug fixing
13
+
## Prerequisites
14
14
15
-
In order to make it easier to get familiar with the codebase we labeled simpler issues using [Good First Issue](https://github.com/parcel-bundler/parcel/issues?q=is%3Aopen+is%3Aissue+label%3A%22%E2%9C%A8+Parcel+2%22+label%3A%22%3Ababy%3A+Good+First+Issue%22) and [Help Wanted](https://github.com/parcel-bundler/parcel/issues?q=is%3Aopen+is%3Aissue+label%3A%22%E2%9C%A8+Parcel+2%22+label%3A%22%3Apray%3A+Help+Wanted%22).
15
+
Before starting make sure you have the following installed:
16
16
17
-
Before starting make sure you have the following requirements installed: [git](https://git-scm.com), [Node](https://nodejs.org), [Yarn](https://yarnpkg.com) and [Rust](https://www.rust-lang.org/tools/install).
-[Flow](https://flow.org/en/docs/editors) IDE autocompletion and type-checking
18
22
19
-
Parcel uses [Flow](https://flow.org) for type checking. If you're using an IDE, make sure to install the [Flow extension](https://flow.org/en/docs/editors/) to ensure your editor's autocomplete and type-checking works as expected.
23
+
## Getting started
20
24
21
-
The process starts by [forking](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) the project and setup a new branch to work in. It's important that the changes are made in separated branches in order to ensure a pull request only includes the commits related to a bug or feature.
25
+
In order to make it easier to get familiar with the codebase we labeled simpler issues using [Good First Issue](https://github.com/parcel-bundler/parcel/issues?q=is%3Aopen+is%3Aissue+label%3A%22%E2%9C%A8+Parcel+2%22+label%3A%22%3Ababy%3A+Good+First+Issue%22)and [Help Wanted](https://github.com/parcel-bundler/parcel/issues?q=is%3Aopen+is%3Aissue+label%3A%22%E2%9C%A8+Parcel+2%22+label%3A%22%3Apray%3A+Help+Wanted%22). You can learn the internals by reading the [documentation](https://parceljs.org/docs) or by starting from `packages/core/core/src/Parcel.js`
22
26
23
-
Clone the forked repository locally and install the dependencies:
27
+
## Pull requests
28
+
29
+
For significant changes, it is recommended that you first [propose your solution](https://github.com/parcel-bundler/parcel/discussions) and gather feedback.
30
+
31
+
**Before submitting a pull request,** you can follow this step by step guide:
32
+
33
+
1.[Fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) the repository and setup a new branch to work in.
34
+
35
+
> 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.
36
+
37
+
2. Run `yarn` and `yarn build-native` in the repository root to install dependencies.
38
+
3. If you fix a bug or introduce a new feature, add tests or ask for help if the use-case is more complex.
39
+
4. Commit the `yarn.lock` file if it has changed.
40
+
5. Check the steps used in [ci](https://github.com/parcel-bundler/parcel/blob/v2/.github/workflows/ci.yml) pass locally.
24
41
25
42
```sh
26
-
git clone https://github.com/USERNAME/parcel.git
27
-
cd parcel
28
-
yarn install
29
-
yarn build-native
43
+
$ yarn build-ts
44
+
$ yarn flow check
45
+
$ yarn lint
46
+
$ yarn test
30
47
```
31
48
32
-
If you want, you can create a temporary example for debugging in the folder `packages/examples`. You can start by copying the `simple` example and try to reproduce the bug. It has everything set up 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. _Please don't commit this example._
49
+
⚠️ Don't modify the `package.json` versioning
33
50
34
-
After you've figured out where the issue originated from and found a fix, try to add a test case or ask for help on how to proceed if the use case is more complex.
51
+
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!
35
52
36
-
Use `yarn test` to run all unit and integration tests. Make sure all tests pass before submitting a pull request.
53
+
## Development workflow
37
54
38
-
Use `yarn format` to make sure we keep the code format consistent.
55
+
The following commands are available:
39
56
40
-
Use `yarn lint` to check for stylistic or unwanted errors.
57
+
-`yarn build-ts` generates the TypeScript type definitions.
58
+
-`yarn flow check` runs the [Flow](https://flow.org) type checking.
59
+
-`yarn format` keeps the code formatting consistent.
60
+
-`yarn lint` checks for stylistic or unwanted errors.
61
+
-`yarn test` runs all the unit and integration tests.
62
+
-`yarn test:integration` runs the integration tests.
63
+
-`yarn test:unit` runs the unit tests.
41
64
42
-
If you want to test out your change outside 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).
65
+
### Debugging
43
66
44
-
## Notes and things to be aware of
67
+
Both VSCode and CLion can be used to debug commands such as the integration test suite.
45
68
46
-
If you're just getting started to understand how the internals work, start from `/packages/core/core/src/Parcel.js`
69
+
-**CLion** is well supported, using default configurations for the relevant language.
70
+
-**VSCode** users can use the JavaScript Debug Terminal or Node.js launch configuration to debug JavaScript. Rust debugging requires a [LLDB](https://lldb.llvm.org/) powered launch configuration, which is available by installing the [CodeLLDB](https://marketplace.visualstudio.com/items?itemName=vadimcn.vscode-lldb) extension.
47
71
48
-
⚠️ You can set `PARCEL_WORKERS` to the number of worker processes to spawn. `PARCEL_WORKERS=0`is handy for debugging, because all code will run on the main thread. You can then place breakpoints in Asset code. (Normally these breakpoints won't trigger, because the code executes in a subprocess.)
72
+
**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.
49
73
50
-
⚠️ When developing plugins, run with `--no-cache` (or pass `shouldDisableCache: true` to `Parcel` options). Parcel uses caching by default, but during development you'll normally pass incomplete results into the cache. This can leave you wondering why you're constantly seeing old results.
74
+
### Plugins
51
75
52
-
You can set `PARCEL_MAX_CONCURRENT_CALLS` to change the limit of concurrent calls per worker.
76
+
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.
53
77
54
-
##Pull requests
78
+
### Working from an example
55
79
56
-
For significant changes, it is recommended that you first [propose your solution](https://github.com/parcel-bundler/parcel/discussions) and gather feedback.
80
+
_Please don't commit these examples._
81
+
82
+
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.
57
83
58
-
A few things to keep in mind before submitting a pull request:
84
+
### Testing outside of the monorepo
59
85
60
-
- do your best to provide relevant test cases
61
-
- if you added an external dependency commit the updated `yarn.lock`
62
-
- don't modify the `package.json` versioning
63
-
- all submissions require review, please be patient
86
+
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.
0 commit comments