github.com/leonlxy/hyperledger@v1.0.0-alpha.0.20170427033203-34922035d248/docs/source/CONTRIBUTING.rst (about) 1 Contributions Welcome! 2 ====================== 3 4 We welcome contributions to the Hyperledger Project in many forms, and 5 there's always plenty to do! 6 7 First things first, please review the Hyperledger Project's `Code of 8 Conduct <https://wiki.hyperledger.org/community/hyperledger-project-code-of-conduct>`__ 9 before participating. It is important that we keep things civil. 10 11 Getting a Linux Foundation account 12 ---------------------------------- 13 14 In order to participate in the development of the Hyperledger Fabric 15 project, you will need a `Linux Foundation 16 account <Gerrit/lf-account.rst>`__. You will need to use your LF ID to 17 access to all the Hyperledger community development tools, including 18 `Gerrit <https://gerrit.hyperledger.org>`__, 19 `Jira <https://jira.hyperledger.org>`__ and the 20 `Wiki <https://wiki.hyperledger.org/start>`__ (for editing, only). 21 22 Setting up your SSH key 23 ~~~~~~~~~~~~~~~~~~~~~~~ 24 25 For Gerrit, before you can submit any change set for review, you will 26 need to register your public SSH key. Login to 27 `Gerrit <https://gerrit.hyperledger.org>`__ with your 28 `LFID <Gerrit/lf-account.rst>`__, and click on your name in the upper 29 right-hand corner of your browser window and then click 'Settings'. In 30 the left-hand margin, you should see a link for 'SSH Public Keys'. 31 Copy-n-paste your `public SSH 32 key <https://help.github.com/articles/generating-an-ssh-key/>`__ into 33 the window and press 'Add'. 34 35 Getting help 36 ------------ 37 38 If you are looking for something to work on, or need some expert 39 assistance in debugging a problem or working out a fix to an issue, our 40 `community <https://www.hyperledger.org/community>`__ is always eager to 41 help. We hang out on 42 `Chat <https://chat.hyperledger.org/channel/fabric/>`__, IRC 43 (#hyperledger on freenode.net) and the `mailing 44 lists <http://lists.hyperledger.org/>`__. Most of us don't bite :grin: 45 and will be glad to help. The only silly question is the one you don't 46 ask. Questions are in fact a great way to help improve the project as 47 they highlight where our documentation could be clearer. 48 49 Requirements and Use Cases 50 -------------------------- 51 52 We have a `Requirements 53 WG <https://wiki.hyperledger.org/groups/requirements/requirements-wg>`__ 54 that is documenting use cases and from those use cases deriving 55 requirements. If you are interested in contributing to this effort, 56 please feel free to join the discussion in 57 `chat <https://chat.hyperledger.org/channel/requirements/>`__. 58 59 Reporting bugs 60 -------------- 61 62 If you are a user and you find a bug, please submit an issue using 63 `JIRA <https://jira.hyperledger.org>`__. Please try to provide 64 sufficient information for someone else to reproduce the issue. One of 65 the project's maintainers should respond to your issue within 24 hours. 66 If not, please bump the issue with a comment and request that it be 67 reviewed. You can also post to the ``#fabric-maintainers`` channel in 68 `chat <https://chat.hyperledger.org/channel/fabric-maintainers>`__. 69 70 Fixing issues and working stories 71 --------------------------------- 72 73 Review the `issues 74 list <https://github.com/hyperledger/fabric/issues>`__ and find 75 something that interests you. You could also check the 76 `"help-wanted" <https://jira.hyperledger.org/issues/?filter=10147>`__ 77 list. It is wise to start with something relatively straight forward and 78 achievable, and that no one is already assigned. If no one is assigned, 79 then assign the issue to yourself. Please be considerate and rescind the 80 assignment if you cannot finish in a reasonable time, or add a comment 81 saying that you are still actively working the issue if you need a 82 little more time. 83 84 Working with a local clone and Gerrit 85 ------------------------------------- 86 87 We are using 88 `Gerrit <https://gerrit.hyperledger.org/r/#/admin/projects/fabric>`__ to 89 manage code contributions. If you are unfamiliar, please review this 90 `document <Gerrit/gerrit.rst>`__ before proceeding. 91 92 After you have familiarized yourself with ``Gerrit``, and maybe played 93 around with the ``lf-sandbox`` 94 `project <https://gerrit.hyperledger.org/r/#/admin/projects/lf-sandbox,branches>`__, 95 you should be ready to set up your local development 96 `environment <dev-setup/devenv.rst>`__. 97 98 Next, try `building the project <dev-setup/build.rst>`__ in your local 99 development environment to ensure that everything is set up correctly. 100 101 `Logging control <Setup/logging-control.rst>`__ describes how to tweak 102 the logging levels of various components within the Fabric. Finally, 103 every source file needs to include a `license 104 header <dev-setup/headers.txt>`__: modified to include a copyright 105 statement for the principle author(s). 106 107 What makes a good change request? 108 --------------------------------- 109 110 - One change at a time. Not five, not three, not ten. One and only one. 111 Why? Because it limits the blast area of the change. If we have a 112 regression, it is much easier to identify the culprit commit than if 113 we have some composite change that impacts more of the code. 114 115 - Include a link to the JIRA story for the change. Why? Because a) we 116 want to track our velocity to better judge what we think we can 117 deliver and when and b) because we can justify the change more 118 effectively. In many cases, there should be some discussion around a 119 proposed change and we want to link back to that from the change 120 itself. 121 122 - Include unit and integration tests (or changes to existing tests) 123 with every change. This does not mean just happy path testing, 124 either. It also means negative testing of any defensive code that it 125 correctly catches input errors. When you write code, you are 126 responsible to test it and provide the tests that demonstrate that 127 your change does what it claims. Why? Because without this we have no 128 clue whether our current code base actually works. 129 130 - Unit tests should have NO external dependencies. You should be able 131 to run unit tests in place with ``go test`` or equivalent for the 132 language. Any test that requires some external dependency (e.g. needs 133 to be scripted to run another component) needs appropriate mocking. 134 Anything else is not unit testing, it is integration testing by 135 definition. Why? Because many open source developers do Test Driven 136 Development. They place a watch on the directory that invokes the 137 tests automagically as the code is changed. This is far more 138 efficient than having to run a whole build between code changes. 139 140 - Minimize the lines of code per CR. Why? Maintainers have day jobs, 141 too. If you send a 1,000 or 2,000 LOC change, how long do you think 142 it takes to review all of that code? Keep your changes to < 200-300 143 LOC, if possible. If you have a larger change, decompose it into 144 multiple independent changess. If you are adding a bunch of new 145 functions to fulfill the requirements of a new capability, add them 146 separately with their tests, and then write the code that uses them 147 to deliver the capability. Of course, there are always exceptions. If 148 you add a small change and then add 300 LOC of tests, you will be 149 forgiven;-) If you need to make a change that has broad impact or a 150 bunch of generated code (protobufs, etc.). Again, there can be 151 exceptions. 152 153 Note: large change requests, e.g. those with more than 300 LOC are more likely 154 than not going to receive a -2, and you'll be asked to refactor the change 155 to conform with this guidance. 156 157 - Do not stack change requests (e.g. submit a CR from the same local branch 158 as your previous CR) unless they are related. This will minimize merge 159 conflicts and allow changes to be merged more quickly. If you stack requests 160 your subsequent requests may be held up because of review comments in the 161 preceding requests. 162 163 - Write a meaningful commit message. Include a meaningful 50 (or less) 164 character title, followed by a blank line, followed by a more 165 comprehensive description of the change. Each change MUST include the JIRA 166 identifier corresponding to the change (e.g. [FAB-1234]). This can be 167 in the title but should also be in the body of the commit message. 168 169 Note that Gerrit will automatically create a hyperlink to the JIRA item. 170 171 e.g. 172 173 :: 174 175 [FAB-1234] fix foobar() panic 176 177 Fix [FAB-1234] added a check to ensure that when foobar(foo string) is called, 178 that there is a non-empty string argument. 179 180 Finally, be responsive. Don't let a change request fester with review 181 comments such that it gets to a point that it requires a rebase. It only 182 further delays getting it merged and adds more work for you - to 183 remediate the merge conflicts. 184 185 Coding guidelines 186 ----------------- 187 188 Be sure to check out the language-specific `style 189 guides <Style-guides/go-style.rst>`__ before making any changes. This 190 will ensure a smoother review. 191 192 Communication 193 -------------- 194 195 We use `RocketChat <https://chat.hyperledger.org/>`__ for communication 196 and Google Hangouts™ for screen sharing between developers. Our 197 development planning and prioritization is done in 198 `JIRA <https://jira.hyperledger.org>`__, and we take longer running 199 discussions/decisions to the `mailing 200 list <http://lists.hyperledger.org/mailman/listinfo/hyperledger-fabric>`__. 201 202 Maintainers 203 ----------- 204 205 The project's `maintainers <MAINTAINERS.rst>`__ are responsible for 206 reviewing and merging all patches submitted for review and they guide 207 the over-all technical direction of the project within the guidelines 208 established by the Hyperledger Project's Technical Steering Committee 209 (TSC). 210 211 Becoming a maintainer 212 ~~~~~~~~~~~~~~~~~~~~~ 213 214 This project is managed under an open governance model as described in 215 our `charter <https://www.hyperledger.org/about/charter>`__. Projects or 216 sub-projects will be lead by a set of maintainers. New sub-projects can 217 designate an initial set of maintainers that will be approved by the 218 top-level project's existing maintainers when the project is first 219 approved. The project's maintainers will, from time-to-time, consider 220 adding or removing a maintainer. An existing maintainer can submit a 221 change set to the `MAINTAINERS.rst <MAINTAINERS.rst>`__ file. If there are 222 less than eight maintainers, a majority of the existing maintainers on 223 that project are required to merge the change set. If there are more 224 than eight existing maintainers, then if five or more of the maintainers 225 concur with the proposal, the change set is then merged and the 226 individual is added to (or alternatively, removed from) the maintainers 227 group. explicit resignation, some infraction of the `code of 228 conduct <https://wiki.hyperledger.org/community/hyperledger-project-code-of-conduct>`__ 229 or consistently demonstrating poor judgement. 230 231 Legal stuff 232 ----------- 233 234 **Note:** Each source file must include a license header for the Apache 235 Software License 2.0. A template of that header can be found 236 `here <https://github.com/hyperledger/fabric/blob/master/docs/dev-setup/headers.txt>`__. 237 238 We have tried to make it as easy as possible to make contributions. This 239 applies to how we handle the legal aspects of contribution. We use the 240 same approach—the `Developer's Certificate of Origin 1.1 241 (DCO) <docs/biz/DCO1.1.txt>`__—that the Linux® Kernel 242 `community <http://elinux.org/Developer_Certificate_Of_Origin>`__ uses 243 to manage code contributions. 244 245 We simply ask that when submitting a patch for review, the developer 246 must include a sign-off statement in the commit message. 247 248 Here is an example Signed-off-by line, which indicates that the 249 submitter accepts the DCO: 250 251 :: 252 253 Signed-off-by: John Doe <john.doe@hisdomain.com> 254 255 You can include this automatically when you commit a change to your 256 local git repository using ``git commit -s``.