Skip to content

Commit 91b47ff

Browse files
Update contributing (#9655)
1 parent 331bed8 commit 91b47ff

File tree

4 files changed

+87
-43
lines changed

4 files changed

+87
-43
lines changed

.gitignore

+17-15
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,25 @@
1-
node_modules/
2-
/target/
3-
.DS_Store
4-
package-lock.json
5-
coverage/
6-
.nyc_output/
71
.cache/
2+
.idea/
3+
.nyc_output/
84
.parcel-cache/
5+
.verdaccio_storage/
6+
.vscode/*
7+
!.vscode/extensions.json
8+
coverage/
99
dist/
1010
lib/
11-
.vscode/
12-
.idea/
13-
*.min.js
14-
# Logs
1511
logs/
16-
*.log
12+
node_modules/
13+
parcel-bundle-reports/
14+
tmp
15+
16+
/target/
17+
18+
.DS_Store
1719
npm-debug.log*
20+
package-lock.json
21+
sourcemap-info.json
1822
yarn-debug.log*
1923
yarn-error.log*
20-
tmp
21-
parcel-bundle-reports/
22-
.verdaccio_storage/
23-
sourcemap-info.json
24+
*.log
25+
*.min.js

.vscode/extensions.json

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
{
2+
// See https://go.microsoft.com/fwlink/?LinkId=827846 to learn about workspace recommendations.
3+
"recommendations": [
4+
"dbaeumer.vscode-eslint",
5+
"editorconfig.editorconfig",
6+
"esbenp.prettier-vscode",
7+
"flowtype.flow-for-vscode",
8+
"vadimcn.vscode-lldb"
9+
]
10+
}

.vscode/launch.json

+9
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,15 @@
44
// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
55
"version": "0.2.0",
66
"configurations": [
7+
{
8+
"name": "Run Integration Tests (lldb)",
9+
"args": ["${workspaceFolder}/node_modules/.bin/_mocha"],
10+
"cwd": "${workspaceFolder}/packages/core/integration-tests",
11+
"program": "node",
12+
"request": "launch",
13+
"sourceLanguages": ["rust"],
14+
"type": "lldb"
15+
},
716
{
817
"args": [
918
"--extensionDevelopmentPath=${workspaceFolder}/packages/utils/parcelforvscode"

CONTRIBUTING.md

+51-28
Original file line numberDiff line numberDiff line change
@@ -10,57 +10,80 @@ Have a question or feature request? Rather than opening an issue, use the [Discu
1010

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

13-
## Getting started with bug fixing
13+
## Prerequisites
1414

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:
1616

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).
17+
- [git](https://git-scm.com)
18+
- [Node](https://nodejs.org) at LTS
19+
- [Yarn](https://yarnpkg.com) at v1
20+
- [Rust](https://www.rust-lang.org/tools/install) stable
21+
- [Flow](https://flow.org/en/docs/editors) IDE autocompletion and type-checking
1822

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
2024

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`
2226

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.
2441

2542
```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
3047
```
3148

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
3350

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!
3552

36-
Use `yarn test` to run all unit and integration tests. Make sure all tests pass before submitting a pull request.
53+
## Development workflow
3754

38-
Use `yarn format` to make sure we keep the code format consistent.
55+
The following commands are available:
3956

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.
4164

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
4366

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.
4568

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.
4771

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.
4973

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
5175

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.
5377

54-
## Pull requests
78+
### Working from an example
5579

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.
5783

58-
A few things to keep in mind before submitting a pull request:
84+
### Testing outside of the monorepo
5985

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.
6487

6588
## Releasing a new version
6689

0 commit comments

Comments
 (0)