2 1. [Overview](#Overview)<br />
3 2. [Minimum Recommended Skillset](#MinSkillset)<br />
4 3. [Required Reading](#ReqReading)<br />
5 4. [Development Practices](#DevelopmentPractices)<br />
6 4.1. [Share Early, Share Often](#ShareEarly)<br />
7 4.2. [Testing](#Testing)<br />
8 4.3. [Code Documentation and Commenting](#CodeDocumentation)<br />
9 4.4. [Model Git Commit Messages](#ModelGitCommitMessages)<br />
10 5. [Code Approval Process](#CodeApproval)<br />
11 5.1 [Code Review](#CodeReview)<br />
12 5.2 [Rework Code (if needed)](#CodeRework)<br />
13 5.3 [Acceptance](#CodeAcceptance)<br />
14 6. [Contribution Standards](#Standards)<br />
15 6.1. [Contribution Checklist](#Checklist)<br />
16 6.2. [Licensing of Contributions](#Licensing)<br />
22 Developing cryptocurrencies is an exciting endeavor that touches a wide variety
23 of areas such as wire protocols, peer-to-peer networking, databases,
24 cryptography, language interpretation (transaction scripts), RPC, and
25 websockets. They also represent a radical shift to the current fiscal system
26 and as a result provide an opportunity to help reshape the entire financial
27 system. There are few projects that offer this level of diversity and impact
30 However, as exciting as it is, one must keep in mind that cryptocurrencies
31 represent real money and introducing bugs and security vulnerabilities can have
32 far more dire consequences than in typical projects where having a small bug is
33 minimal by comparison. In the world of cryptocurrencies, even the smallest bug
34 in the wrong area can cost people a significant amount of money. For this
35 reason, the btcd suite has a formalized and rigorous development process which
36 is outlined on this page.
38 We highly encourage code contributions, however it is imperative that you adhere
39 to the guidelines established on this page.
41 <a name="MinSkillset" />
43 ### 2. Minimum Recommended Skillset
45 The following list is a set of core competencies that we recommend you possess
46 before you really start attempting to contribute code to the project. These are
47 not hard requirements as we will gladly accept code contributions as long as
48 they follow the guidelines set forth on this page. That said, if you don't have
49 the following basic qualifications you will likely find it quite difficult to
52 - A reasonable understanding of bitcoin at a high level (see the
53 [Required Reading](#ReqReading) section for the original white paper)
54 - Experience in some type of C-like language
55 - An understanding of data structures and their performance implications
56 - Familiarity with unit testing
57 - Debugging experience
58 - Ability to understand not only the area you are making a change in, but also
59 the code your change relies on, and the code which relies on your changed code
61 Building on top of those core competencies, the recommended skill set largely
62 depends on the specific areas you are looking to contribute to. For example,
63 if you wish to contribute to the cryptography code, you should have a good
64 understanding of the various aspects involved with cryptography such as the
65 security and performance implications.
67 <a name="ReqReading" />
69 ### 3. Required Reading
71 - [Effective Go](http://golang.org/doc/effective_go.html) - The entire btcd
72 suite follows the guidelines in this document. For your code to be accepted,
73 it must follow the guidelines therein.
74 - [Original Satoshi Whitepaper](http://www.google.com/url?sa=t&rct=j&q=&esrc=s&source=web&cd=1&cad=rja&ved=0CCkQFjAA&url=http%3A%2F%2Fbitcoin.org%2Fbitcoin.pdf&ei=os3VUuH8G4SlsASV74GoAg&usg=AFQjCNEipPLigou_1MfB7DQjXCNdlylrBg&sig2=FaHDuT5z36GMWDEnybDJLg&bvm=bv.59378465,d.b2I) - This is the white paper that started it all. Having a solid
75 foundation to build on will make the code much more comprehensible.
77 <a name="DevelopmentPractices" />
79 ### 4. Development Practices
81 Developers are expected to work in their own trees and submit pull requests when
82 they feel their feature or bug fix is ready for integration into the master
85 <a name="ShareEarly" />
87 ### 4.1 Share Early, Share Often
89 We firmly believe in the share early, share often approach. The basic premise
90 of the approach is to announce your plans **before** you start work, and once
91 you have started working, craft your changes into a stream of small and easily
94 This approach has several benefits:
96 - Announcing your plans to work on a feature **before** you begin work avoids
98 - It permits discussions which can help you achieve your goals in a way that is
99 consistent with the existing architecture
100 - It minimizes the chances of you spending time and energy on a change that
101 might not fit with the consensus of the community or existing architecture and
102 potentially be rejected as a result
103 - Incremental development helps ensure you are on the right track with regards
104 to the rest of the community
105 - The quicker your changes are merged to master, the less time you will need to
106 spend rebasing and otherwise trying to keep up with the main code base
112 One of the major design goals of all core btcd packages is to aim for complete
113 test coverage. This is financial software so bugs and regressions can cost
114 people real money. For this reason every effort must be taken to ensure the
115 code is as accurate and bug-free as possible. Thorough testing is a good way to
116 help achieve that goal.
118 Unless a new feature you submit is completely trivial, it will probably be
119 rejected unless it is also accompanied by adequate test coverage for both
120 positive and negative conditions. That is to say, the tests must ensure your
121 code works correctly when it is fed correct data as well as incorrect data
124 Go provides an excellent test framework that makes writing test code and
125 checking coverage statistics straight forward. For more information about the
126 test coverage tools, see the [golang cover blog post](http://blog.golang.org/cover).
128 A quick summary of test practices follows:
129 - All new code should be accompanied by tests that ensure the code behaves
130 correctly when given expected values, and, perhaps even more importantly, that
131 it handles errors gracefully
132 - When you fix a bug, it should be accompanied by tests which exercise the bug
133 to both prove it has been resolved and to prevent future regressions
135 <a name="CodeDocumentation" />
137 ### 4.3 Code Documentation and Commenting
139 - At a minimum every function must be commented with its intended purpose and
140 any assumptions that it makes
141 - Function comments must always begin with the name of the function per
142 [Effective Go](http://golang.org/doc/effective_go.html)
143 - Function comments should be complete sentences since they allow a wide
144 variety of automated presentations such as [godoc.org](https://godoc.org)
145 - The general rule of thumb is to look at it as if you were completely
146 unfamiliar with the code and ask yourself, would this give me enough
147 information to understand what this function does and how I'd probably want
149 - Exported functions should also include detailed information the caller of the
150 function will likely need to know and/or understand:<br /><br />
153 // convert a compact uint32 to big.Int
154 func CompactToBig(compact uint32) *big.Int {
158 // CompactToBig converts a compact representation of a whole number N to a
159 // big integer. The representation is similar to IEEE754 floating point
162 // Like IEEE754 floating point, there are three basic components: the sign,
163 // the exponent, and the mantissa. They are broken out as follows:
165 // * the most significant 8 bits represent the unsigned base 256 exponent
166 // * bit 23 (the 24th bit) represents the sign bit
167 // * the least significant 23 bits represent the mantissa
169 // -------------------------------------------------
170 // | Exponent | Sign | Mantissa |
171 // -------------------------------------------------
172 // | 8 bits [31-24] | 1 bit [23] | 23 bits [22-00] |
173 // -------------------------------------------------
175 // The formula to calculate N is:
176 // N = (-1^sign) * mantissa * 256^(exponent-3)
178 // This compact form is only used in bitcoin to encode unsigned 256-bit numbers
179 // which represent difficulty targets, thus there really is not a need for a
180 // sign bit, but it is implemented here to stay consistent with bitcoind.
181 func CompactToBig(compact uint32) *big.Int {
183 - Comments in the body of the code are highly encouraged, but they should
184 explain the intention of the code as opposed to just calling out the
188 // return err if amt is less than 5460
195 // Treat transactions with amounts less than the amount which is considered dust
201 **NOTE:** The above should really use a constant as opposed to a magic number,
202 but it was left as a magic number to show how much of a difference a good
205 <a name="ModelGitCommitMessages" />
207 ### 4.4 Model Git Commit Messages
209 This project prefers to keep a clean commit history with well-formed commit
210 messages. This section illustrates a model commit message and provides a bit
211 of background for it. This content was originally created by Tim Pope and made
212 available on his website, however that website is no longer active, so it is
215 Here’s a model Git commit message:
218 Short (50 chars or less) summary of changes
220 More detailed explanatory text, if necessary. Wrap it to about 72
221 characters or so. In some contexts, the first line is treated as the
222 subject of an email and the rest of the text as the body. The blank
223 line separating the summary from the body is critical (unless you omit
224 the body entirely); tools like rebase can get confused if you run the
227 Write your commit message in the present tense: "Fix bug" and not "Fixed
228 bug." This convention matches up with commit messages generated by
229 commands like git merge and git revert.
231 Further paragraphs come after blank lines.
233 - Bullet points are okay, too
234 - Typically a hyphen or asterisk is used for the bullet, preceded by a
235 single space, with blank lines in between, but conventions vary here
236 - Use a hanging indent
239 Prefix the summary with the subsystem/package when possible. Many other
240 projects make use of the code and this makes it easier for them to tell when
241 something they're using has changed. Have a look at [past
242 commits](https://github.com/btcsuite/btcd/commits/master) for examples of
245 Here are some of the reasons why wrapping your commit messages to 72 columns is
248 - git log doesn’t do any special special wrapping of the commit messages. With
249 the default pager of less -S, this means your paragraphs flow far off the edge
250 of the screen, making them difficult to read. On an 80 column terminal, if we
251 subtract 4 columns for the indent on the left and 4 more for symmetry on the
252 right, we’re left with 72 columns.
253 - git format-patch --stdout converts a series of commits to a series of emails,
254 using the messages for the message body. Good email netiquette dictates we
255 wrap our plain text emails such that there’s room for a few levels of nested
256 reply indicators without overflow in an 80 column terminal.
258 <a name="CodeApproval" />
260 ### 5. Code Approval Process
262 This section describes the code approval process that is used for code
263 contributions. This is how to get your changes into btcd.
265 <a name="CodeReview" />
269 All code which is submitted will need to be reviewed before inclusion into the
270 master branch. This process is performed by the project maintainers and usually
271 other committers who are interested in the area you are working in as well.
273 ##### Code Review Timeframe
275 The timeframe for a code review will vary greatly depending on factors such as
276 the number of other pull requests which need to be reviewed, the size and
277 complexity of the contribution, how well you followed the guidelines presented
278 on this page, and how easy it is for the reviewers to digest your commits. For
279 example, if you make one monolithic commit that makes sweeping changes to things
280 in multiple subsystems, it will obviously take much longer to review. You will
281 also likely be asked to split the commit into several smaller, and hence more
284 Keeping the above in mind, most small changes will be reviewed within a few
285 days, while large or far reaching changes may take weeks. This is a good reason
286 to stick with the [Share Early, Share Often](#ShareOften) development practice
289 ##### What is the review looking for?
291 The review is mainly ensuring the code follows the [Development Practices](#DevelopmentPractices)
292 and [Code Contribution Standards](#Standards). However, there are a few other
293 checks which are generally performed as follows:
295 - The code is stable and has no stability or security concerns
296 - The code is properly using existing APIs and generally fits well into the
298 - The change is not something which is deemed inappropriate by community
301 <a name="CodeRework" />
303 ### 5.2 Rework Code (if needed)
305 After the code review, the change will be accepted immediately if no issues are
306 found. If there are any concerns or questions, you will be provided with
307 feedback along with the next steps needed to get your contribution merged with
308 master. In certain cases the code reviewer(s) or interested committers may help
309 you rework the code, but generally you will simply be given feedback for you to
310 make the necessary changes.
312 This process will continue until the code is finally accepted.
314 <a name="CodeAcceptance" />
318 Once your code is accepted, it will be integrated with the master branch.
319 Typically it will be rebased and fast-forward merged to master as we prefer to
320 keep a clean commit history over a tangled weave of merge commits. However,
321 regardless of the specific merge method used, the code will be integrated with
322 the master branch and the pull request will be closed.
324 Rejoice as you will now be listed as a [contributor](https://github.com/btcsuite/btcd/graphs/contributors)!
326 <a name="Standards" />
328 ### 6. Contribution Standards
330 <a name="Checklist" />
332 ### 6.1. Contribution Checklist
334 - [ ] All changes are Go version 1.3 compliant
335 - [ ] The code being submitted is commented according to the
336 [Code Documentation and Commenting](#CodeDocumentation) section
337 - [ ] For new code: Code is accompanied by tests which exercise both
338 the positive and negative (error paths) conditions (if applicable)
339 - [ ] For bug fixes: Code is accompanied by new tests which trigger
340 the bug being fixed to prevent regressions
341 - [ ] Any new logging statements use an appropriate subsystem and
343 - [ ] Code has been formatted with `go fmt`
344 - [ ] Running `go test` does not fail any tests
345 - [ ] Running `go vet` does not report any issues
346 - [ ] Running [golint](https://github.com/golang/lint) does not
347 report any **new** issues that did not already exist
349 <a name="Licensing" />
351 ### 6.2. Licensing of Contributions
353 All contributions must be licensed with the
354 [ISC license](https://github.com/btcsuite/btcd/blob/master/LICENSE). This is
355 the same license as all of the code in the btcd suite.