1 | # Contributing to swc
|
2 |
|
3 | Thank you for your interest in contributing to swc! Good places to start are this document, ARCHITECTURE.md, which describes the high-level structure of swc and E-easy bugs on the issue tracker.
|
4 |
|
5 |
|
6 |
|
7 | ## Code of Conduct
|
8 |
|
9 | All contributors are expected to follow our [Code of Conduct].
|
10 |
|
11 | ## Bug reports
|
12 |
|
13 | We can't fix what we don't know about, so please report problems liberally. This
|
14 | includes problems with understanding the documentation, unhelpful error messages,
|
15 | and unexpected behavior.
|
16 |
|
17 | Opening an issue is as easy as following [this link][new-issues] and filling out
|
18 | the fields. Here's a template that you can use to file an issue, though it's not
|
19 | necessary to use it exactly:
|
20 |
|
21 | <short summary of the problem>
|
22 |
|
23 | I tried this: <minimal example that causes the problem>
|
24 |
|
25 | I expected to see this happen: <explanation>
|
26 |
|
27 | Instead, this happened: <explanation>
|
28 |
|
29 | I'm using <output of `swc --version`>
|
30 |
|
31 | All three components are important: what you did, what you expected, what
|
32 | happened instead. Please use https://gist.github.com/ if your examples run long.
|
33 |
|
34 | ## Feature requests
|
35 |
|
36 | Please feel free to open an issue or to send a pr.
|
37 |
|
38 | ## Working on issues
|
39 |
|
40 | If you're looking for somewhere to start, check out the [E-easy][E-Easy] and
|
41 | [E-mentor][E-mentor] tags.
|
42 |
|
43 | Feel free to ask for guidelines on how to tackle a problem on [gitter][] or open a
|
44 | [new issue][new-issues]. This is especially important if you want to add new
|
45 | features to swc or make large changes to the already existing code-base.
|
46 | swc's core developers will do their best to provide help.
|
47 |
|
48 | If you start working on an already-filed issue, post a comment on this issue to
|
49 | let people know that somebody is working it. Feel free to ask for comments if
|
50 | you are unsure about the solution you would like to submit.
|
51 |
|
52 | We use the "fork and pull" model [described here][development-models], where
|
53 | contributors push changes to their personal fork and create pull requests to
|
54 | bring those changes into the source repository. This process is partly
|
55 | automated: Pull requests are made against swc's master-branch, tested and
|
56 | reviewed. Once a change is approved to be merged, a friendly bot merges the
|
57 | changes into an internal branch, runs the full test-suite on that branch
|
58 | and only then merges into master. This ensures that swc's master branch
|
59 | passes the test-suite at all times.
|
60 |
|
61 | Your basic steps to get going:
|
62 |
|
63 | * Fork swc and create a branch from master for the issue you are working on.
|
64 | * Please adhere to the code style that you see around the location you are
|
65 | working on.
|
66 | * [Commit as you go][githelp].
|
67 | * Include tests that cover all non-trivial code. The existing tests
|
68 | in `test/` provide templates on how to test swc's behavior in a
|
69 | sandbox-environment. The internal crate `testing` provides a vast amount
|
70 | of helpers to minimize boilerplate. See [`testing/lib.rs`] for an
|
71 | introduction to writing tests.
|
72 | * Make sure `cargo test` passes.
|
73 | * All code changes are expected to comply with the formatting suggested by `rustfmt`.
|
74 | You can use `rustup component add --toolchain nightly rustfmt-preview` to install `rustfmt` and use
|
75 | `rustfmt +nightly --unstable-features --skip-children` on the changed files to automatically format your code.
|
76 | * Push your commits to GitHub and create a pull request against swc's `master` branch.
|
77 |
|
78 | ## Getting your development environment set up
|
79 |
|
80 | After cloning the project there are a few steps required to get the project running.
|
81 |
|
82 | 1. Fetch submodules to pull ECMAScript test suites.
|
83 |
|
84 | ```bash
|
85 | git submodule update --init --recursive
|
86 | ```
|
87 |
|
88 | 2. Install js dependencies.
|
89 |
|
90 | ```bash
|
91 | yarn add browserslist
|
92 | ( cd ecmascript/transforms; yarn install )
|
93 | ```
|
94 |
|
95 | 3. Setup some environment variables which is required for tests.
|
96 |
|
97 | ```bash
|
98 | export RUSTFLAGS='--cfg procmacro2_semver_exempt'
|
99 | export RUST_BACKTRACE=full
|
100 | export PATH="$PATH:$PWD/ecmascript/transforms/node_modules/.bin"
|
101 | ```
|
102 |
|
103 | 4. Run tests
|
104 |
|
105 | ```bash
|
106 | cargo test --all --all-features
|
107 | ```
|
108 |
|
109 | ## Pull requests
|
110 |
|
111 | After the pull request is made, one of the swc project developers will review your code.
|
112 | The review-process will make sure that the proposed changes are sound.
|
113 | Please give the assigned reviewer sufficient time, especially during weekends.
|
114 | If you don't get a reply, you may poke the core developers on [gitter].
|
115 |
|
116 | A merge of swc's master-branch and your changes is immediately queued
|
117 | to be tested after the pull request is made. In case unforeseen
|
118 | problems are discovered during this step (e.g. a failure on a platform you
|
119 | originally did not develop on), you may ask for guidance. Push additional
|
120 | commits to your branch to tackle these problems.
|
121 |
|
122 | The reviewer might point out changes deemed necessary. Please add them as
|
123 | extra commits; this ensures that the reviewer can see what has changed since
|
124 | the code was previously reviewed. Large or tricky changes may require several
|
125 | passes of review and changes.
|
126 |
|
127 | Once the reviewer approves your pull request, a friendly bot picks it up
|
128 | and merges it into swc's `master` branch.
|
129 |
|
130 | ## Contributing to the documentation
|
131 |
|
132 | TODO
|
133 |
|
134 | ## Issue Triage
|
135 |
|
136 | Sometimes an issue will stay open, even though the bug has been fixed. And
|
137 | sometimes, the original bug may go stale because something has changed in the
|
138 | meantime.
|
139 |
|
140 | It can be helpful to go through older bug reports and make sure that they are
|
141 | still valid. Load up an older issue, double check that it's still true, and
|
142 | leave a comment letting us know if it is or is not. The [least recently
|
143 | updated sort][lru] is good for finding issues like this.
|
144 |
|
145 | Contributors with sufficient permissions on the Rust-repository can help by
|
146 | adding labels to triage issues:
|
147 |
|
148 | * Yellow, **A**-prefixed labels state which **area** of the project an issue
|
149 | relates to.
|
150 |
|
151 | * Magenta, **B**-prefixed labels identify bugs which are **blockers**.
|
152 |
|
153 | * Red, **C**-prefixed labels represent the **category** of an issue.
|
154 | In particular, **C-feature-request** marks *proposals* for new features. If
|
155 | an issue is **C-feature-request**, but is not **Feature accepted**,
|
156 | then it was not thoroughly discussed, and might need some additional design
|
157 | or perhaps should be implemented as an external subcommand first. Ping
|
158 | @swc-projcet/swc if you want to send a PR for an such issue.
|
159 |
|
160 | * Green, **E**-prefixed labels explain the level of **experience** or
|
161 | **effort** necessary to fix the issue. [**E-mentor**][E-mentor] issues also
|
162 | have some instructions on how to get started.
|
163 |
|
164 | * Purple gray, **O**-prefixed labels are the **operating system** or platform
|
165 | that this issue is specific to.
|
166 |
|
167 | * Orange, **P**-prefixed labels indicate a bug's **priority**.
|
168 |
|
169 | * Light orange, **L**-prefixed labels indicate language related to the bug.
|
170 |
|
171 |
|
172 | [gist]: https://gist.github.com/
|
173 | [new-issues]: https://github.com/swc-project/swc/issues/new
|
174 | [E-easy]: https://github.com/swc-project/swc/labels/E-easy
|
175 | [E-mentor]: https://github.com/swc-project/swc/labels/E-mentor
|
176 | [Code of Conduct]: https://www.rust-lang.org/conduct.html
|
177 | [gitter]: https://gitter.im/swcproject/Lobby
|
178 | [`testing/lib.rs`]: https://github.com/swc-project/swc/blob/master/testing/src/lib.rs
|
179 | [irlo]: https://internals.rust-lang.org/
|
180 | [subcommands]: https://doc.rust-lang.org/cargo/reference/external-tools.html#custom-subcommands
|