2021-11-15 07:26:04 +03:00
|
|
|
# Contributing to SWC
|
2018-12-04 09:11:50 +03:00
|
|
|
|
2021-11-15 07:26:04 +03:00
|
|
|
Thank you for your interest in contributing to SWC! Good places to start are:
|
|
|
|
|
|
|
|
- Reading this document
|
|
|
|
- Reading the high-level structure of SWC in [ARCHITECTURE.md](ARCHITECTURE.md)
|
|
|
|
- [E-easy][e-easy] labeled issues on the [issue tracker][issue-tracker]
|
2018-12-04 09:11:50 +03:00
|
|
|
|
|
|
|
## Code of Conduct
|
|
|
|
|
|
|
|
All contributors are expected to follow our [Code of Conduct].
|
|
|
|
|
|
|
|
## Bug reports
|
|
|
|
|
2021-11-15 07:26:04 +03:00
|
|
|
We can't fix what we don't know about, so please report problems. This
|
2019-03-25 09:43:17 +03:00
|
|
|
includes problems with understanding the documentation, unhelpful error messages,
|
2018-12-04 09:11:50 +03:00
|
|
|
and unexpected behavior.
|
|
|
|
|
2021-11-15 07:26:04 +03:00
|
|
|
You can open a new issue by following [this link][new-issues] and choosing one of the issue templates.
|
2018-12-04 09:11:50 +03:00
|
|
|
|
|
|
|
## Feature requests
|
|
|
|
|
2021-11-15 07:26:04 +03:00
|
|
|
Please feel free to open an issue using the [feature request template][new-issues].
|
2018-12-04 09:11:50 +03:00
|
|
|
|
|
|
|
## Working on issues
|
|
|
|
|
2021-02-28 09:55:20 +03:00
|
|
|
If you're looking for somewhere to start, check out the [E-easy][e-easy] and
|
|
|
|
[E-mentor][e-mentor] tags.
|
2018-12-04 09:11:50 +03:00
|
|
|
|
2021-11-15 10:38:31 +03:00
|
|
|
Feel free to ask for guidelines on how to tackle a problem on [Discord][discord] or open a
|
2018-12-04 09:11:50 +03:00
|
|
|
[new issue][new-issues]. This is especially important if you want to add new
|
2021-11-15 07:26:04 +03:00
|
|
|
features to SWC or make large changes to the already existing code-base.
|
|
|
|
The SWC core developers will do their best to provide help.
|
2018-12-04 09:11:50 +03:00
|
|
|
|
|
|
|
If you start working on an already-filed issue, post a comment on this issue to
|
|
|
|
let people know that somebody is working it. Feel free to ask for comments if
|
|
|
|
you are unsure about the solution you would like to submit.
|
|
|
|
|
|
|
|
We use the "fork and pull" model [described here][development-models], where
|
|
|
|
contributors push changes to their personal fork and create pull requests to
|
|
|
|
bring those changes into the source repository. This process is partly
|
2021-11-15 07:26:04 +03:00
|
|
|
automated: Pull requests are made against SWC's repository, tested and
|
2018-12-04 09:11:50 +03:00
|
|
|
reviewed. Once a change is approved to be merged, a friendly bot merges the
|
|
|
|
changes into an internal branch, runs the full test-suite on that branch
|
2021-11-15 10:52:45 +03:00
|
|
|
and only then merges into main. This ensures that SWC passes the test-suite at all times.
|
2018-12-04 09:11:50 +03:00
|
|
|
|
2021-11-15 07:26:04 +03:00
|
|
|
Steps to get started:
|
2018-12-04 09:11:50 +03:00
|
|
|
|
2021-11-15 10:52:45 +03:00
|
|
|
- Fork SWC and create a branch from main for the issue you are working on.
|
2021-07-29 08:18:21 +03:00
|
|
|
- Make sure you have the `make` utility installed, along with Rust and C/C++
|
|
|
|
compilers.
|
|
|
|
- Please adhere to the code style that you see around the location you are
|
|
|
|
working on.
|
|
|
|
- [Commit as you go][githelp].
|
|
|
|
- Include tests that cover all non-trivial code. The existing tests
|
2021-11-17 07:50:41 +03:00
|
|
|
in `tests/` provide templates on how to test SWC's behavior in a
|
2021-07-29 08:18:21 +03:00
|
|
|
sandbox-environment. The internal crate `testing` provides a vast amount
|
|
|
|
of helpers to minimize boilerplate. See [`testing/lib.rs`] for an
|
|
|
|
introduction to writing tests.
|
2021-11-15 07:26:04 +03:00
|
|
|
- Run `cargo test` and make sure that it passes.
|
2021-07-29 08:18:21 +03:00
|
|
|
- All code changes are expected to comply with the formatting suggested by `rustfmt`.
|
|
|
|
You can use `rustup component add --toolchain nightly rustfmt-preview` to install `rustfmt` and use
|
|
|
|
`rustfmt +nightly --unstable-features --skip-children` on the changed files to automatically format your code.
|
2021-11-15 10:52:45 +03:00
|
|
|
- Push your commits to GitHub and create a pull request against the `swc-project/swc` `main` branch.
|
2018-12-04 09:11:50 +03:00
|
|
|
|
2019-10-28 15:53:07 +03:00
|
|
|
## Getting your development environment set up
|
|
|
|
|
|
|
|
After cloning the project there are a few steps required to get the project running.
|
|
|
|
|
2020-02-09 22:48:55 +03:00
|
|
|
1. Fetch submodules to pull ECMAScript test suites.
|
2019-10-28 15:53:07 +03:00
|
|
|
|
2020-02-09 22:48:55 +03:00
|
|
|
```bash
|
|
|
|
git submodule update --init --recursive
|
|
|
|
```
|
2019-10-28 15:53:07 +03:00
|
|
|
|
2020-02-09 22:48:55 +03:00
|
|
|
2. Install js dependencies.
|
|
|
|
|
|
|
|
```bash
|
2021-11-16 13:31:02 +03:00
|
|
|
yarn
|
2021-11-17 07:50:41 +03:00
|
|
|
( cd crates/swc_ecma_transforms; yarn )
|
2020-02-09 22:48:55 +03:00
|
|
|
```
|
|
|
|
|
|
|
|
3. Setup some environment variables which is required for tests.
|
|
|
|
|
|
|
|
```bash
|
|
|
|
export RUST_BACKTRACE=full
|
2021-11-17 07:50:41 +03:00
|
|
|
export PATH="$PATH:$PWD/crates/swc_ecma_transforms/node_modules/.bin"
|
2021-11-16 13:31:02 +03:00
|
|
|
export RUST_MIN_STACK=16777216
|
2020-02-09 22:48:55 +03:00
|
|
|
```
|
|
|
|
|
2021-02-28 09:55:20 +03:00
|
|
|
4. Install deno, if you are going to work on the bundler.
|
|
|
|
|
|
|
|
See [official install guide of deno](https://deno.land/manual/getting_started/installation) to install it.
|
|
|
|
|
2021-11-16 13:31:02 +03:00
|
|
|
5. Ensure you're using Node.JS >= 16
|
|
|
|
|
|
|
|
Since tests make use of `atob` which was only introduced in node 16.
|
|
|
|
|
|
|
|
6. Run tests
|
2020-02-09 22:48:55 +03:00
|
|
|
|
|
|
|
```bash
|
|
|
|
cargo test --all --all-features
|
|
|
|
```
|
2018-12-04 09:11:50 +03:00
|
|
|
|
|
|
|
## Pull requests
|
|
|
|
|
2021-11-15 07:26:04 +03:00
|
|
|
After the pull request is made, one of the SWC project developers will review your code.
|
2018-12-04 09:11:50 +03:00
|
|
|
The review-process will make sure that the proposed changes are sound.
|
|
|
|
Please give the assigned reviewer sufficient time, especially during weekends.
|
2021-11-15 10:38:31 +03:00
|
|
|
If you don't get a reply, you may ping the core developers on [Discord][discord].
|
2018-12-04 09:11:50 +03:00
|
|
|
|
2021-11-15 10:52:45 +03:00
|
|
|
A merge of SWC's main-branch and your changes is immediately queued
|
2018-12-04 09:11:50 +03:00
|
|
|
to be tested after the pull request is made. In case unforeseen
|
|
|
|
problems are discovered during this step (e.g. a failure on a platform you
|
|
|
|
originally did not develop on), you may ask for guidance. Push additional
|
|
|
|
commits to your branch to tackle these problems.
|
|
|
|
|
|
|
|
The reviewer might point out changes deemed necessary. Please add them as
|
|
|
|
extra commits; this ensures that the reviewer can see what has changed since
|
|
|
|
the code was previously reviewed. Large or tricky changes may require several
|
|
|
|
passes of review and changes.
|
|
|
|
|
|
|
|
Once the reviewer approves your pull request, a friendly bot picks it up
|
2021-11-15 10:52:45 +03:00
|
|
|
and merges it into the SWC `main` branch.
|
2018-12-04 09:11:50 +03:00
|
|
|
|
|
|
|
## Contributing to the documentation
|
|
|
|
|
2021-11-15 10:52:45 +03:00
|
|
|
The SWC documentation can be found at [`swc-project/website`](https://github.com/swc-project/website/tree/main/pages/docs).
|
2021-11-15 07:26:04 +03:00
|
|
|
|
|
|
|
At the bottom of each page on [swc.rs](https://swc.rs) there is a `Edit this page on GitHub` button that immediately links to the right page to edit.
|
2018-12-04 09:11:50 +03:00
|
|
|
|
|
|
|
## Issue Triage
|
|
|
|
|
|
|
|
Sometimes an issue will stay open, even though the bug has been fixed. And
|
|
|
|
sometimes, the original bug may go stale because something has changed in the
|
|
|
|
meantime.
|
|
|
|
|
|
|
|
It can be helpful to go through older bug reports and make sure that they are
|
|
|
|
still valid. Load up an older issue, double check that it's still true, and
|
|
|
|
leave a comment letting us know if it is or is not. The [least recently
|
|
|
|
updated sort][lru] is good for finding issues like this.
|
|
|
|
|
2021-11-15 07:26:04 +03:00
|
|
|
Contributors with sufficient permissions on the SWC repository can help by
|
2018-12-04 09:11:50 +03:00
|
|
|
adding labels to triage issues:
|
|
|
|
|
2021-07-29 08:18:21 +03:00
|
|
|
- Yellow, **A**-prefixed labels state which **area** of the project an issue
|
|
|
|
relates to.
|
2018-12-04 09:11:50 +03:00
|
|
|
|
2021-07-29 08:18:21 +03:00
|
|
|
- Magenta, **B**-prefixed labels identify bugs which are **blockers**.
|
2018-12-04 09:11:50 +03:00
|
|
|
|
2021-07-29 08:18:21 +03:00
|
|
|
- Red, **C**-prefixed labels represent the **category** of an issue.
|
|
|
|
In particular, **C-feature-request** marks _proposals_ for new features. If
|
|
|
|
an issue is **C-feature-request**, but is not **Feature accepted**,
|
|
|
|
then it was not thoroughly discussed, and might need some additional design
|
|
|
|
or perhaps should be implemented as an external subcommand first. Ping
|
2021-11-15 07:26:04 +03:00
|
|
|
`@swc-project/swc` if you want to send a PR for an such issue.
|
2018-12-04 09:11:50 +03:00
|
|
|
|
2021-07-29 08:18:21 +03:00
|
|
|
- Green, **E**-prefixed labels explain the level of **experience** or
|
|
|
|
**effort** necessary to fix the issue. [**E-mentor**][e-mentor] issues also
|
|
|
|
have some instructions on how to get started.
|
2018-12-04 09:11:50 +03:00
|
|
|
|
2021-07-29 08:18:21 +03:00
|
|
|
- Purple gray, **O**-prefixed labels are the **operating system** or platform
|
|
|
|
that this issue is specific to.
|
2018-12-04 09:11:50 +03:00
|
|
|
|
2021-07-29 08:18:21 +03:00
|
|
|
- Orange, **P**-prefixed labels indicate a bug's **priority**.
|
|
|
|
- Light orange, **L**-prefixed labels indicate language related to the bug.
|
2018-12-04 09:11:50 +03:00
|
|
|
|
|
|
|
[gist]: https://gist.github.com/
|
2021-11-15 07:26:04 +03:00
|
|
|
[new-issues]: https://github.com/swc-project/swc/issues/new/choose
|
2021-02-28 09:55:20 +03:00
|
|
|
[e-easy]: https://github.com/swc-project/swc/labels/E-easy
|
|
|
|
[e-mentor]: https://github.com/swc-project/swc/labels/E-mentor
|
|
|
|
[code of conduct]: https://www.rust-lang.org/conduct.html
|
2021-11-17 07:50:41 +03:00
|
|
|
[development-models]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/getting-started/about-collaborative-development-models
|
2021-12-31 16:05:47 +03:00
|
|
|
[discord]: https://discord.com/invite/GnHbXTdZz6
|
2021-11-17 07:50:41 +03:00
|
|
|
[`testing/lib.rs`]: https://github.com/swc-project/swc/blob/main/crates/testing/src/lib.rs
|
2018-12-04 09:11:50 +03:00
|
|
|
[irlo]: https://internals.rust-lang.org/
|
2021-11-17 07:50:41 +03:00
|
|
|
[lru]: https://docs.github.com/en/search-github/getting-started-with-searching-on-github/sorting-search-results#sort-by-updated-date
|
2019-03-25 09:43:17 +03:00
|
|
|
[subcommands]: https://doc.rust-lang.org/cargo/reference/external-tools.html#custom-subcommands
|
2021-11-15 07:26:04 +03:00
|
|
|
[issue-tracker]: https://github.com/swc-project/swc/issues
|