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