|
1 | 1 | Contributing to Rust-Lightning
|
2 | 2 | ==============================
|
3 | 3 |
|
4 |
| -The Rust-Lightning project operates an open contributor model where anyone is |
5 |
| -welcome to contribute towards development in the form of peer review, documentation, |
6 |
| -testing and patches. |
7 |
| - |
8 |
| -Anyone is invited to contribute without regard to technical experience, "expertise", OSS |
9 |
| -experience, age, or other concern. However, the development of cryptocurrencies demands a |
10 |
| -high-level of rigor, adversarial thinking, thorough testing and risk-minimization. |
11 |
| -Any bug may cost users real money. That being said, we deeply welcome people contributing |
12 |
| -for the first time to an open source project or pick up Rust while contributing. Don't be shy, |
13 |
| -you'll learn. |
14 |
| - |
15 |
| -Communications Channels |
| 4 | +The `rust-lightning` project operates an open contributor model where anyone is |
| 5 | +welcome to contribute towards development in the form of peer review, |
| 6 | +documentation, testing and patches. |
| 7 | + |
| 8 | +Anyone is invited to contribute without regard to technical experience, |
| 9 | +"expertise", OSS experience, age, or other concern. However, the development of |
| 10 | +cryptocurrencies demands a high-level of rigor, adversarial thinking, thorough |
| 11 | +testing and risk-minimization. Any bug may cost users real money. That being |
| 12 | +said, we deeply welcome people contributing for the first time to an open source |
| 13 | +project or pick up Rust while contributing. Don't be shy, you'll learn. |
| 14 | + |
| 15 | +Communication Channels |
16 | 16 | -----------------------
|
17 | 17 |
|
18 |
| -Communication about Rust-Lightning happens primarily on #ldk-dev on the |
19 |
| -[LDK slack](http://www.lightningdevkit.org/), but also #rust-bitcoin on IRC Freenode. |
| 18 | +Communication about the development of LDK and `rust-lightning` happens |
| 19 | +primarily on the [LDK Discord](https://discord.gg/5AcknnMfBw) in the `#ldk-dev` |
| 20 | +channel. Additionally, live LDK devevelopment meetings are held every other |
| 21 | +Monday 19:00 UTC in the [LDK Dev Jitsi Meeting |
| 22 | +Room](https://meet.jit.si/ldkdevmeeting). Upcoming events can be found in the |
| 23 | +[LDK calendar](https://calendar.google.com/calendar/embed?src=c_e6fv6vlshbpoob2mmbvblkkoj4%40group.calendar.google.com). |
| 24 | + |
| 25 | +Contributors starting out with the Rust language are welcome to discuss and ask |
| 26 | +for help in the `#rust-101` channel on LDK Discord. |
20 | 27 |
|
21 | 28 | Discussion about code base improvements happens in GitHub issues and on pull
|
22 | 29 | requests.
|
23 | 30 |
|
24 |
| -Major projects are tracked [here](https://github.com/lightningdevkit/rust-lightning/projects). |
| 31 | +The LDK roadmap is tracked [here](https://github.com/orgs/lightningdevkit/projects/2). |
| 32 | + |
25 | 33 | Major milestones are tracked [here](https://github.com/lightningdevkit/rust-lightning/milestones?direction=asc&sort=title&state=open).
|
26 | 34 |
|
27 | 35 | Getting Started
|
28 | 36 | ---------------
|
29 | 37 |
|
30 | 38 | First and foremost, start small.
|
31 | 39 |
|
32 |
| -This doesn't mean don't be ambitious with the breadth and depth of your contributions but rather |
33 |
| -understand the project culture before investing an asymmetric number of hours on |
34 |
| -development compared to your merged work. |
| 40 | +This doesn't mean don't be ambitious with the breadth and depth of your |
| 41 | +contributions but rather understand the project culture before investing an |
| 42 | +asymmetric number of hours on development compared to your merged work. |
35 | 43 |
|
36 | 44 | Browsing through the [meeting minutes](https://github.com/lightningdevkit/rust-lightning/wiki/Meetings)
|
37 |
| -is a good first step. You will learn who is working on what, how releases are drafted, what are the |
38 |
| -pending tasks to deliver, where you can contribute review bandwidth, etc. |
| 45 | +is a good first step. You will learn who is working on what, how releases are |
| 46 | +drafted, what are the pending tasks to deliver, where you can contribute review |
| 47 | +bandwidth, etc. |
39 | 48 |
|
40 |
| -Even if you have an extensive open source background or sound software engineering skills, consider |
41 |
| -that the reviewers' comprehension of the code is as much important as technical correctness. |
| 49 | +Even if you have an extensive open source background or sound software |
| 50 | +engineering skills, consider that the reviewers' comprehension of the code is as |
| 51 | +much important as technical correctness. |
42 | 52 |
|
43 |
| -It's very welcome to ask for review, either on IRC or LDK Slack. And also for reviewers, it's nice |
44 |
| -to provide timelines when you hope to fulfill the request while bearing in mind for both sides that's |
45 |
| -a "soft" commitment. |
| 53 | +It's very welcome to ask for review on LDK Discord. And also for reviewers, it's |
| 54 | +nice to provide timelines when you hope to fulfill the request while bearing in |
| 55 | +mind for both sides that's a "soft" commitment. |
46 | 56 |
|
47 |
| -If you're eager to increase the velocity of the dev process, reviewing other contributors work is |
48 |
| -the best you can do while waiting review on yours. |
| 57 | +If you're eager to increase the velocity of the dev process, reviewing other |
| 58 | +contributors work is the best you can do while waiting review on yours. |
49 | 59 |
|
50 |
| -Also, getting familiar with the [glossary](GLOSSARY.md) will streamline discussions with regular contributors. |
| 60 | +Also, getting familiar with the [glossary](GLOSSARY.md) will streamline |
| 61 | +discussions with regular contributors. |
51 | 62 |
|
52 | 63 | Contribution Workflow
|
53 | 64 | ---------------------
|
@@ -80,89 +91,94 @@ our GitHub Actions). Also, the compatibility for LDK object serialization is
|
80 | 91 | currently ensured back to and including crate version 0.0.99 (see the
|
81 | 92 | [changelog](CHANGELOG.md)).
|
82 | 93 |
|
83 |
| -Commits should cover both the issue fixed and the solution's rationale. |
84 |
| -These [guidelines](https://chris.beams.io/posts/git-commit/) should be kept in mind. |
| 94 | +Commits should cover both the issue fixed and the solution's rationale. These |
| 95 | +[guidelines](https://chris.beams.io/posts/git-commit/) should be kept in mind. |
85 | 96 |
|
86 |
| -To facilitate communication with other contributors, the project is making use of |
87 |
| -GitHub's "assignee" field. First check that no one is assigned and then comment |
88 |
| -suggesting that you're working on it. If someone is already assigned, don't hesitate |
89 |
| -to ask if the assigned party or previous commenters are still working on it if it has |
90 |
| -been awhile. |
| 97 | +To facilitate communication with other contributors, the project is making use |
| 98 | +of GitHub's "assignee" field. First check that no one is assigned and then |
| 99 | +comment suggesting that you're working on it. If someone is already assigned, |
| 100 | +don't hesitate to ask if the assigned party or previous commenters are still |
| 101 | +working on it if it has been awhile. |
91 | 102 |
|
92 | 103 | Peer review
|
93 | 104 | -----------
|
94 | 105 |
|
95 | 106 | Anyone may participate in peer review which is expressed by comments in the pull
|
96 | 107 | request. Typically reviewers will review the code for obvious errors, as well as
|
97 | 108 | test out the patch set and opine on the technical merits of the patch. PR should
|
98 |
| -be reviewed first on the conceptual level before focusing on code style or grammar |
99 |
| -fixes. |
| 109 | +be reviewed first on the conceptual level before focusing on code style or |
| 110 | +grammar fixes. |
100 | 111 |
|
101 | 112 | Coding Conventions
|
102 | 113 | ------------------
|
103 | 114 |
|
104 | 115 | Use tabs. If you want to align lines, use spaces. Any desired alignment should
|
105 | 116 | display fine at any tab-length display setting.
|
106 | 117 |
|
107 |
| -Our CI enforces [clippy's](https://github.com/rust-lang/rust-clippy) default linting |
108 |
| -[settings](https://rust-lang.github.io/rust-clippy/rust-1.39.0/index.html). |
109 |
| -This includes all lint groups except for nursery, pedantic, and cargo in addition to allowing the following lints: |
110 |
| -`erasing_op`, `never_loop`, `if_same_then_else`. |
| 118 | +Our CI enforces [clippy's](https://github.com/rust-lang/rust-clippy) default |
| 119 | +linting |
| 120 | +[settings](https://rust-lang.github.io/rust-clippy/rust-1.39.0/index.html). This |
| 121 | +includes all lint groups except for nursery, pedantic, and cargo in addition to |
| 122 | +allowing the following lints: `erasing_op`, `never_loop`, `if_same_then_else`. |
111 | 123 |
|
112 |
| -If you use rustup, feel free to lint locally, otherwise you can just push to CI for automated linting. |
| 124 | +If you use rustup, feel free to lint locally, otherwise you can just push to CI |
| 125 | +for automated linting. |
113 | 126 |
|
114 | 127 | ```bash
|
115 | 128 | rustup component add clippy
|
116 | 129 | cargo clippy
|
117 | 130 | ```
|
118 | 131 |
|
119 |
| -Significant structures that users persist should always have their serialization methods (usually |
120 |
| -`Writeable::write` and `ReadableArgs::read`) begin with |
| 132 | +Significant structures that users persist should always have their serialization |
| 133 | +methods (usually `Writeable::write` and `ReadableArgs::read`) begin with |
121 | 134 | `write_ver_prefix!()`/`read_ver_prefix!()` calls, and end with calls to
|
122 | 135 | `write_tlv_fields!()`/`read_tlv_fields!()`.
|
123 | 136 |
|
124 |
| -Updates to the serialized format which has implications for backwards or forwards compatibility |
125 |
| -must be included in release notes. |
| 137 | +Updates to the serialized format which has implications for backwards or |
| 138 | +forwards compatibility must be included in release notes. |
126 | 139 |
|
127 | 140 | Security
|
128 | 141 | --------
|
129 | 142 |
|
130 |
| -Security is the primary focus of Rust-Lightning; disclosure of security vulnerabilites |
131 |
| -helps prevent user loss of funds. If you believe a vulnerability may affect other Lightning |
132 |
| -implementations, please inform them. |
| 143 | +Security is the primary focus of `rust-lightning`; disclosure of security |
| 144 | +vulnerabilites helps prevent user loss of funds. If you believe a vulnerability |
| 145 | +may affect other Lightning implementations, please inform them. |
133 | 146 |
|
134 |
| -Note that Rust-Lightning is currently considered "pre-production" during this time, there |
135 |
| -is no special handling of security issues. Please simply open an issue on Github. |
| 147 | +You can find further information on submitting (possible) vulnerabilities in the |
| 148 | +[security policy](SECURITY.md). |
136 | 149 |
|
137 | 150 | Testing
|
138 | 151 | -------
|
139 | 152 |
|
140 |
| -Related to the security aspect, Rust-Lightning developers take testing |
141 |
| -very seriously. Due to the modular nature of the project, writing new functional |
142 |
| -tests is easy and good test coverage of the codebase is an important goal. Refactoring |
143 |
| -the project to enable fine-grained unit testing is also an ongoing effort. |
| 153 | +Related to the security aspect, `rust-lightning` developers take testing very |
| 154 | +seriously. Due to the modular nature of the project, writing new functional |
| 155 | +tests is easy and good test coverage of the codebase is an important goal. |
| 156 | +Refactoring the project to enable fine-grained unit testing is also an ongoing |
| 157 | +effort. |
144 | 158 |
|
145 | 159 | Fuzzing is heavily encouraged: you will find all related material under `fuzz/`
|
146 | 160 |
|
147 |
| -Mutation testing is work-in-progress; any contribution there would be warmly welcomed. |
| 161 | +Mutation testing is work-in-progress; any contribution there would be warmly |
| 162 | +welcomed. |
148 | 163 |
|
149 | 164 | C/C++ Bindings
|
150 | 165 | --------------
|
151 | 166 |
|
152 |
| -You can learn more about the C/C++ bindings that are made available by reading the |
153 |
| -[C/C++ Bindings README](lightning-c-bindings/README.md). If you are not using the C/C++ bindings, |
154 |
| -you likely don't need to worry about them, and during their early experimental phase we are not |
155 |
| -requiring that pull requests keep the bindings up to date (and, thus, pass the bindings_check CI |
156 |
| -run). If you wish to ensure your PR passes the bindings generation phase, you should run the |
157 |
| -`genbindings.sh` script in the top of the directory tree to generate, build, and test C bindings on |
158 |
| -your local system. |
| 167 | +You can learn more about the C/C++ bindings that are made available by reading |
| 168 | +the [C/C++ Bindings README](https://github.com/lightningdevkit/ldk-c-bindings/blob/main/lightning-c-bindings/README.md). |
| 169 | +If you are not using the C/C++ bindings, you likely don't need to worry about |
| 170 | +them, and during their early experimental phase we are not requiring that pull |
| 171 | +requests keep the bindings up to date (and, thus, pass the `bindings_check` CI |
| 172 | +run). If you wish to ensure your PR passes the bindings generation phase, you |
| 173 | +should run the `genbindings.sh` script in the top of the directory tree to |
| 174 | +generate, build, and test C bindings on your local system. |
159 | 175 |
|
160 | 176 | Going further
|
161 | 177 | -------------
|
162 | 178 |
|
163 |
| -You may be interested by Jon Atack guide on [How to review Bitcoin Core PRs](https://github.com/jonatack/bitcoin-development/blob/master/how-to-review-bitcoin-core-prs.md) |
| 179 | +You may be interested by Jon Atack's guide on [How to review Bitcoin Core PRs](https://github.com/jonatack/bitcoin-development/blob/master/how-to-review-bitcoin-core-prs.md) |
164 | 180 | and [How to make Bitcoin Core PRs](https://github.com/jonatack/bitcoin-development/blob/master/how-to-make-bitcoin-core-prs.md).
|
165 |
| -While there are differences between the projects in terms of context and maturity, many |
166 |
| -of the suggestions offered apply to this project. |
| 181 | +While there are differences between the projects in terms of context and |
| 182 | +maturity, many of the suggestions offered apply to this project. |
167 | 183 |
|
168 | 184 | Overall, have fun :)
|
0 commit comments