|
1 | 1 | # Contributing to `twiggy`
|
2 | 2 |
|
3 |
| -Hi! We'd love to have your contributions! If you want help or mentorship, reach |
4 |
| -out to us in a GitHub issue, or ping `fitzgen` in [`#rust-wasm` on |
5 |
| -`irc.mozilla.org`](irc://irc.mozilla.org#rust-wasm) and introduce yourself. |
6 |
| - |
7 |
| -<!-- START doctoc generated TOC please keep comment here to allow auto update --> |
8 |
| -<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> |
9 |
| - |
10 |
| - |
11 |
| -- [Code of Conduct](#code-of-conduct) |
12 |
| -- [Building and Testing](#building-and-testing) |
13 |
| - - [Building for the Native Target](#building-for-the-native-target) |
14 |
| - - [Building for the `wasm32-unknown-unknown` Target](#building-for-the-wasm32-unknown-unknown-target) |
15 |
| - - [Testing](#testing) |
16 |
| - - [Authoring New Tests](#authoring-new-tests) |
17 |
| - - [Updating Test Expectations](#updating-test-expectations) |
18 |
| -- [Automatic Code Formatting](#automatic-code-formatting) |
19 |
| -- [Pull Requests](#pull-requests) |
20 |
| -- [Contributions We Want](#contributions-we-want) |
21 |
| -- [Team](#team) |
22 |
| - |
23 |
| -<!-- END doctoc generated TOC please keep comment here to allow auto update --> |
24 |
| - |
25 |
| -## Code of Conduct |
26 |
| - |
27 |
| -We abide by the [Rust Code of Conduct][coc] and ask that you do as well. |
28 |
| - |
29 |
| -[coc]: https://www.rust-lang.org/en-US/conduct.html |
30 |
| - |
31 |
| -## Building and Testing |
32 |
| - |
33 |
| -### Building for the Native Target |
34 |
| - |
35 |
| -``` |
36 |
| -$ cargo build --all --exclude twiggy-wasm-api |
37 |
| -``` |
38 |
| - |
39 |
| -### Building for the `wasm32-unknown-unknown` Target |
40 |
| - |
41 |
| -``` |
42 |
| -$ JOB=wasm ./ci/script.sh |
43 |
| -``` |
44 |
| - |
45 |
| -### Testing |
46 |
| - |
47 |
| -``` |
48 |
| -$ cargo test --all --exclude twiggy-wasm-api |
49 |
| -``` |
50 |
| - |
51 |
| -#### Authoring New Tests |
52 |
| - |
53 |
| -Integration tests live in the `twiggy/tests` directory: |
54 |
| - |
55 |
| -``` |
56 |
| -twiggy/tests |
57 |
| -├── expectations |
58 |
| -├── fixtures |
59 |
| -└── tests.rs |
60 |
| -``` |
61 |
| - |
62 |
| -* The `twiggy/tests/tests.rs` file contains the `#[test]` definitions. |
63 |
| - |
64 |
| -* The `twiggy/tests/fixtures` directory contains input binaries for tests. |
65 |
| - |
66 |
| -* The `twiggy/tests/expectations` directory contains the expected output of test |
67 |
| - commands. |
68 |
| - |
69 |
| -#### Updating Test Expectations |
70 |
| - |
71 |
| -To automatically update all test expectations, you can run the tests with the |
72 |
| -`TWIGGY_UPDATE_TEST_EXPECTATIONS=1` environment variable set. Make sure that you |
73 |
| -look at the changes before committing them, and that they match your intentions! |
74 |
| - |
75 |
| -## Automatic Code Formatting |
76 |
| - |
77 |
| -We use [`rustfmt`](https://github.com/rust-lang-nursery/rustfmt) to enforce a |
78 |
| -consistent code style across the whole code base. |
79 |
| - |
80 |
| -You can install the latest version of `rustfmt` with this command: |
81 |
| - |
82 |
| -``` |
83 |
| -$ rustup update |
84 |
| -$ rustup component add rustfmt-preview |
85 |
| -``` |
86 |
| - |
87 |
| -Ensure that `~/.rustup/toolchains/$YOUR_HOST_TARGET/bin/` is on your `$PATH`. |
88 |
| - |
89 |
| -Once that is taken care of, you can (re)format all code by running this command |
90 |
| -from the root of the repository: |
91 |
| - |
92 |
| -``` |
93 |
| -$ cargo fmt --all |
94 |
| -``` |
95 |
| - |
96 |
| -## Pull Requests |
97 |
| - |
98 |
| -All pull requests must be reviewed and approved of by at least one [team](#team) |
99 |
| -member before merging. See [Contributions We Want](#contributions-we-want) for |
100 |
| -details on what should be included in what kind of pull request. |
101 |
| - |
102 |
| -## Contributions We Want |
103 |
| - |
104 |
| -* **Bug fixes!** Include a regression test. |
105 |
| - |
106 |
| -* **Support for more binary formats!** See [this issue][more-formats] for |
107 |
| - details. |
108 |
| - |
109 |
| -* **New analyses and queries!** Help expose information about monomorphizations |
110 |
| - or inlining. Report diffs between two versions of the same binary. Etc... |
111 |
| - |
112 |
| -If you make two of these kinds of contributions, you should seriously consider |
113 |
| -joining our [team](#team)! |
114 |
| - |
115 |
| -Where we need help: |
116 |
| - |
117 |
| -* Issues labeled ["help wanted"][help-wanted] are issues where we could use a |
118 |
| - little help from you. |
119 |
| - |
120 |
| -* Issues labeled ["mentored"][mentored] are issues that don't really involve any |
121 |
| - more investigation, just implementation. We've outlined what needs to be done, |
122 |
| - and a [team](#team) member has volunteered to help whoever claims the issue to |
123 |
| - implement it, and get the implementation merged. |
124 |
| - |
125 |
| -* Issues labeled ["good first issue"][gfi] are issues where fixing them would be |
126 |
| - a great introduction to the code base. |
127 |
| - |
128 |
| -[more-formats]: https://github.com/rustwasm/twiggy/issues/4 |
129 |
| -[help-wanted]: https://github.com/rustwasm/twiggy/labels/help%20wanted |
130 |
| -[mentored]: https://github.com/rustwasm/twiggy/labels/mentored |
131 |
| -[gfi]: https://github.com/rustwasm/twiggy/labels/good%20first%20issue |
132 |
| - |
133 |
| -## Team |
134 |
| - |
135 |
| -| [<img alt="fitzgen" src="https://github.com/fitzgen.png" width="117">](https://github.com/fitzgen) | [<img alt="data-pup" src="https://github.com/data-pup.png" width="117">](https://github.com/data-pup) | |
136 |
| -|:---:|:---:| |
137 |
| -| [`fitzgen`](https://github.com/fitzgen) | [`data-pup`](https://github.com/data-pup) | |
138 |
| - |
139 |
| -Larger, more nuanced decisions about design, architecture, breaking changes, |
140 |
| -trade offs, etc are made by team consensus. In other words, decisions on things |
141 |
| -that aren't straightforward improvements or bug fixes to things that already |
142 |
| -exist in `twiggy`. If consensus can't be made, then `fitzgen` has the last |
143 |
| -word. |
144 |
| - |
145 |
| -**We need more team members!** |
146 |
| -[Drop a comment on this issue if you are interested in joining.][join] |
147 |
| - |
148 |
| -[join]: https://github.com/rustwasm/twiggy/issues/3 |
| 3 | +[Read the "Contributing to Twiggy" section of the Twiggy guide!](https://rustwasm.github.io/twiggy/contributing/index.html) |
0 commit comments