github.com/true-sqn/fabric@v2.1.1+incompatible/docs/source/CONTRIBUTING.rst (about) 1 .. note:: Users who are migrating from Gerrit to GitHub: You can follow simple 2 Git workflows to move your development from Gerrit to GitHub. After 3 forking the Fabric repo, simply push the branches you want to save from 4 your current Gerrit-based local repo to your remote forked repository. 5 Once you've pushed the changes you want to save, simply delete your 6 local Gerrit-based repository and clone your fork. 7 8 For a basic Git workflow recommendation please see our doc at 9 :doc:`github/github`. 10 11 Contributions Welcome! 12 ====================== 13 14 .. toctree:: 15 :maxdepth: 1 16 :hidden: 17 18 style_guide 19 20 We welcome contributions to Hyperledger in many forms, and 21 there's always plenty to do! 22 23 First things first, please review the Hyperledger `Code of 24 Conduct <https://wiki.hyperledger.org/community/hyperledger-project-code-of-conduct>`__ 25 before participating. It is important that we keep things civil. 26 27 .. node:: If you want to contribute to this documentation, please check out the :doc:`style_guide`. 28 29 Ways to contribute 30 ------------------ 31 There are many ways you can contribute to Hyperledger Fabric, both as a user and 32 as a developer. 33 34 As a user: 35 36 - `Making Feature/Enhancement Proposals`_ 37 - `Reporting bugs`_ 38 - Help test an upcoming Epic on the 39 `release roadmap <https://jira.hyperledger.org/secure/Dashboard.jspa?selectPageId=10104>`_. 40 Contact the Epic assignee via the Jira work item or on 41 `RocketChat <https://chat.hyperledger.org>`_. 42 43 As a developer: 44 45 - If you only have a little time, consider picking up a 46 `"help-wanted" <https://jira.hyperledger.org/issues/?filter=10147>`_ task, 47 see `Fixing issues and working stories`_. 48 - If you can commit to full-time development, either propose a new feature 49 (see `Making Feature/Enhancement Proposals`_) and 50 bring a team to implement it, or join one of the teams working on an existing Epic. 51 If you see an Epic that interests you on the 52 `release roadmap <https://jira.hyperledger.org/secure/Dashboard.jspa?selectPageId=10104>`_, 53 contact the Epic assignee via the Jira work item or on `RocketChat <https://chat.hyperledger.org/>`_. 54 55 Getting a Linux Foundation account 56 ---------------------------------- 57 58 In order to participate in the development of the Hyperledger Fabric 59 project, you will need a Linux Foundation 60 account. Once you have a LF ID you will be able to 61 access all the Hyperledger community tools, including 62 `Jira issue management <https://jira.hyperledger.org>`__, 63 `RocketChat <https://chat.hyperledger.org/>`__, and the 64 `Wiki <https://wiki.hyperledger.org/display/fabric/Hyperledger+Fabric>`__ (for editing, only). 65 66 Follow the steps below to create a Linux Foundation account if you don't 67 already have one. 68 69 1. Go to the `Linux Foundation ID 70 website <https://identity.linuxfoundation.org/>`__. 71 72 2. Select the option ``I need to create a Linux Foundation ID``, and fill 73 out the form that appears. 74 75 3. Wait a few minutes, then look for an email message with the subject line: 76 "Validate your Linux Foundation ID email". 77 78 4. Open the received URL to validate your email address. 79 80 5. Verify that your browser displays the message 81 ``You have successfully validated your e-mail address``. 82 83 6. Access `Jira issue management <https://jira.hyperledger.org>`__, or 84 `RocketChat <https://chat.hyperledger.org/>`__. 85 86 Project Governance 87 ------------------ 88 89 Hyperledger Fabric is managed under an open governance model as described in 90 our `charter <https://www.hyperledger.org/about/charter>`__. Projects and 91 sub-projects are lead by a set of maintainers. New sub-projects can 92 designate an initial set of maintainers that will be approved by the 93 top-level project's existing maintainers when the project is first 94 approved. 95 96 Maintainers 97 ~~~~~~~~~~~ 98 99 The Fabric project is lead by the project's top level `maintainers <https://github.com/hyperledger/fabric/blob/master/MAINTAINERS.md>`__. 100 The maintainers are responsible for reviewing and merging all patches submitted 101 for review, and they guide the overall technical direction of the project within 102 the guidelines established by the Hyperledger Technical Steering Committee (TSC). 103 104 Becoming a maintainer 105 ~~~~~~~~~~~~~~~~~~~~~ 106 107 The project's maintainers will, from time-to-time, consider 108 adding or removing a maintainer. An existing maintainer can submit a 109 change set to the `maintainers <https://github.com/hyperledger/fabric/blob/master/MAINTAINERS.md>`__ file. A nominated 110 Contributor may become a Maintainer by a majority approval of the proposal 111 by the existing Maintainers. Once approved, the change set is then merged 112 and the individual is added to (or alternatively, removed from) the maintainers 113 group. Maintainers may be removed by explicit resignation, for prolonged 114 inactivity (3 or more months), or for some infraction of the `code of conduct 115 <https://wiki.hyperledger.org/community/hyperledger-project-code-of-conduct>`__ 116 or by consistently demonstrating poor judgement. A maintainer removed for 117 inactivity should be restored following a sustained resumption of contributions 118 and reviews (a month or more) demonstrating a renewed commitment to the project. 119 120 Release cadence 121 ~~~~~~~~~~~~~~~ 122 123 The Fabric maintainers have settled on a quarterly (approximately) release 124 cadence (see `releases <https://github.com/hyperledger/fabric#releases>`__). 125 At any given time, there will be a stable LTS (long term support) release branch, 126 as well as the master branch for upcoming new features. 127 Follow the discussion on the #fabric-release channel in RocketChat. 128 129 Making Feature/Enhancement Proposals 130 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 131 132 First, take time to review 133 `JIRA <https://jira.hyperledger.org/issues/?filter=12524>`__ 134 to be sure that there isn't already an open (or recently closed) proposal for the 135 same function. If there isn't, to make a proposal we recommend that you open a 136 JIRA Epic or Story, whichever seems to best fit the circumstance and 137 link or inline a "one pager" of the proposal that states what the feature would 138 do and, if possible, how it might be implemented. It would help also to make a 139 case for why the feature should be added, such as identifying specific use 140 case(s) for which the feature is needed and a case for what the benefit would be 141 should the feature be implemented. Once the JIRA issue is created, and the 142 "one pager" either attached, inlined in the description field, or a link to a 143 publicly accessible document is added to the description, send an introductory 144 email to the fabric@lists.hyperledger.org mailing list linking the 145 JIRA issue, and soliciting feedback. 146 147 Discussion of the proposed feature should be conducted in the JIRA issue itself, 148 so that we have a consistent pattern within our community as to where to find 149 design discussion. 150 151 Getting the support of three or more of the Hyperledger Fabric maintainers for 152 the new feature will greatly enhance the probability that the feature's related 153 PRs will be included in a subsequent release. 154 155 Maintainers meeting 156 ~~~~~~~~~~~~~~~~~~~ 157 158 The maintainers hold regular maintainers meetings. 159 The purpose of the maintainers meeting is to plan for and review the progress of 160 releases, and to discuss the technical and operational direction of the project 161 and sub-projects. 162 163 Please see the 164 `wiki <https://wiki.hyperledger.org/display/fabric/Maintainer+Meetings>`__ 165 for maintainer meeting details. 166 167 New feature/enhancement proposals as described above should be presented to a 168 maintainers meeting for consideration, feedback and acceptance. 169 170 Release roadmap 171 ~~~~~~~~~~~~~~~ 172 173 The Fabric release roadmap of epics is maintained in 174 `JIRA <https://jira.hyperledger.org/secure/Dashboard.jspa?selectPageId=10104>`__. 175 176 Communications 177 ~~~~~~~~~~~~~~ 178 179 We use `RocketChat <https://chat.hyperledger.org/>`__ for communication 180 and Google Hangouts™ for screen sharing between developers. Our 181 development planning and prioritization is done in 182 `JIRA <https://jira.hyperledger.org>`__, and we take longer running 183 discussions/decisions to the `mailing 184 list <https://lists.hyperledger.org/mailman/listinfo/hyperledger-fabric>`__. 185 186 Contribution guide 187 ------------------ 188 189 Install prerequisites 190 ~~~~~~~~~~~~~~~~~~~~~ 191 192 Before we begin, if you haven't already done so, you may wish to check that 193 you have all the :doc:`prerequisites <prereqs>` installed on the platform(s) 194 on which you'll be developing blockchain applications and/or operating 195 Hyperledger Fabric. 196 197 Getting help 198 ~~~~~~~~~~~~ 199 200 If you are looking for something to work on, or need some expert 201 assistance in debugging a problem or working out a fix to an issue, our 202 `community <https://www.hyperledger.org/community>`__ is always eager to 203 help. We hang out on 204 `Chat <https://chat.hyperledger.org/channel/fabric/>`__, IRC 205 (#hyperledger on freenode.net) and the `mailing 206 lists <https://lists.hyperledger.org/>`__. Most of us don't bite :grin: 207 and will be glad to help. The only silly question is the one you don't 208 ask. Questions are in fact a great way to help improve the project as 209 they highlight where our documentation could be clearer. 210 211 Reporting bugs 212 ~~~~~~~~~~~~~~ 213 214 If you are a user and you have found a bug, please submit an issue using 215 `JIRA <https://jira.hyperledger.org/secure/Dashboard.jspa?selectPageId=10104>`__. 216 Before you create a new JIRA issue, please try to search the existing items to 217 be sure no one else has previously reported it. If it has been previously 218 reported, then you might add a comment that you also are interested in seeing 219 the defect fixed. 220 221 .. note:: If the defect is security-related, please follow the Hyperledger 222 `security bug reporting process <https://wiki.hyperledger.org/display/HYP/Defect+Response>`__. 223 224 If it has not been previously reported, you may either submit a PR with a 225 well documented commit message describing the defect and the fix, or you 226 may create a new JIRA. Please try to provide 227 sufficient information for someone else to reproduce the 228 issue. One of the project's maintainers should respond to your issue within 24 229 hours. If not, please bump the issue with a comment and request that it be 230 reviewed. You can also post to the relevant Hyperledger Fabric channel in 231 `Hyperledger Chat <https://chat.hyperledger.org>`__. For example, a doc bug should 232 be broadcast to ``#fabric-documentation``, a database bug to ``#fabric-ledger``, 233 and so on... 234 235 Submitting your fix 236 ~~~~~~~~~~~~~~~~~~~ 237 238 If you just submitted a JIRA for a bug you've discovered, and would like to 239 provide a fix, we would welcome that gladly! Please assign the JIRA issue to 240 yourself, then submit a pull request (PR). Please refer to :doc:`github/github` 241 for a detailed workflow. 242 243 Fixing issues and working stories 244 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 245 246 Review the `issues 247 list <https://jira.hyperledger.org/issues/?filter=10580>`__ and find 248 something that interests you. You could also check the 249 `"help-wanted" <https://jira.hyperledger.org/issues/?filter=10147>`__ 250 list. It is wise to start with something relatively straight forward and 251 achievable, and that no one is already assigned. If no one is assigned, 252 then assign the issue to yourself. Please be considerate and rescind the 253 assignment if you cannot finish in a reasonable time, or add a comment 254 saying that you are still actively working the issue if you need a 255 little more time. 256 257 Reviewing submitted Pull Requests (PRs) 258 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 259 260 Another way to contribute and learn about Hyperledger Fabric is to help the 261 maintainers with the review of the PRs that are open. Indeed 262 maintainers have the difficult role of having to review all the PRs 263 that are being submitted and evaluate whether they should be merged or 264 not. You can review the code and/or documentation changes, test the 265 changes, and tell the submitters and maintainers what you think. Once 266 your review and/or test is complete just reply to the PR with your 267 findings, by adding comments and/or voting. A comment saying something 268 like "I tried it on system X and it works" or possibly "I got an error 269 on system X: xxx " will help the maintainers in their evaluation. As a 270 result, maintainers will be able to process PRs faster and everybody 271 will gain from it. 272 273 Just browse through `the open PRs on GitHub 274 <https://github.com/hyperledger/fabric/pulls>`__ to get started. 275 276 PR Aging 277 ~~~~~~~~ 278 279 As the Fabric project has grown, so too has the backlog of open PRs. One 280 problem that nearly all projects face is effectively managing that backlog 281 and Fabric is no exception. In an effort to keep the backlog of Fabric and 282 related project PRs manageable, we are introducing an aging policy which 283 will be enforced by bots. This is consistent with how other large projects 284 manage their PR backlog. 285 286 PR Aging Policy 287 ~~~~~~~~~~~~~~~ 288 289 The Fabric project maintainers will automatically monitor all PR activity for 290 delinquency. If a PR has not been updated in 2 weeks, a reminder comment will be 291 added requesting that the PR either be updated to address any outstanding 292 comments or abandoned if it is to be withdrawn. If a delinquent PR goes another 293 2 weeks without an update, it will be automatically abandoned. If a PR has aged 294 more than 2 months since it was originally submitted, even if it has activity, 295 it will be flagged for maintainer review. 296 297 If a submitted PR has passed all validation but has not been reviewed in 72 298 hours (3 days), it will be flagged to the #fabric-pr-review channel daily until 299 it receives a review comment(s). 300 301 This policy applies to all official Fabric projects (fabric, fabric-ca, 302 fabric-samples, fabric-test, fabric-sdk-node, fabric-sdk-java, fabric-gateway-java, 303 fabric-chaincode-node, fabric-chaincode-java, fabric-chaincode-evm, 304 fabric-baseimage, and fabric-amcl). 305 306 Setting up development environment 307 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 308 309 Next, try :doc:`building the project <dev-setup/build>` in your local 310 development environment to ensure that everything is set up correctly. 311 312 What makes a good pull request? 313 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 314 315 - One change at a time. Not five, not three, not ten. One and only one. 316 Why? Because it limits the blast area of the change. If we have a 317 regression, it is much easier to identify the culprit commit than if 318 we have some composite change that impacts more of the code. 319 320 - Include a link to the JIRA story for the change. Why? Because a) we 321 want to track our velocity to better judge what we think we can 322 deliver and when and b) because we can justify the change more 323 effectively. In many cases, there should be some discussion around a 324 proposed change and we want to link back to that from the change 325 itself. 326 327 - Include unit and integration tests (or changes to existing tests) 328 with every change. This does not mean just happy path testing, 329 either. It also means negative testing of any defensive code that it 330 correctly catches input errors. When you write code, you are 331 responsible to test it and provide the tests that demonstrate that 332 your change does what it claims. Why? Because without this we have no 333 clue whether our current code base actually works. 334 335 - Unit tests should have NO external dependencies. You should be able 336 to run unit tests in place with ``go test`` or equivalent for the 337 language. Any test that requires some external dependency (e.g. needs 338 to be scripted to run another component) needs appropriate mocking. 339 Anything else is not unit testing, it is integration testing by 340 definition. Why? Because many open source developers do Test Driven 341 Development. They place a watch on the directory that invokes the 342 tests automagically as the code is changed. This is far more 343 efficient than having to run a whole build between code changes. See 344 `this definition <http://artofunittesting.com/definition-of-a-unit-test/>`__ 345 of unit testing for a good set of criteria to keep in mind for writing 346 effective unit tests. 347 348 - Minimize the lines of code per PR. Why? Maintainers have day jobs, 349 too. If you send a 1,000 or 2,000 LOC change, how long do you think 350 it takes to review all of that code? Keep your changes to < 200-300 351 LOC, if possible. If you have a larger change, decompose it into 352 multiple independent changes. If you are adding a bunch of new 353 functions to fulfill the requirements of a new capability, add them 354 separately with their tests, and then write the code that uses them 355 to deliver the capability. Of course, there are always exceptions. If 356 you add a small change and then add 300 LOC of tests, you will be 357 forgiven;-) If you need to make a change that has broad impact or a 358 bunch of generated code (protobufs, etc.). Again, there can be 359 exceptions. 360 361 .. note:: Large pull requests, e.g. those with more than 300 LOC are more than likely 362 not going to receive an approval, and you'll be asked to refactor 363 the change to conform with this guidance. 364 365 - Write a meaningful commit message. Include a meaningful 55 (or less) 366 character title, followed by a blank line, followed by a more 367 comprehensive description of the change. Each change MUST include the JIRA 368 identifier corresponding to the change (e.g. [FAB-1234]). This can be 369 in the title but should also be in the body of the commit message. 370 371 .. note:: Example commit message: 372 373 :: 374 375 [FAB-1234] fix foobar() panic 376 377 Fix [FAB-1234] added a check to ensure that when foobar(foo string) 378 is called, that there is a non-empty string argument. 379 380 Finally, be responsive. Don't let a pull request fester with review 381 comments such that it gets to a point that it requires a rebase. It only 382 further delays getting it merged and adds more work for you - to 383 remediate the merge conflicts. 384 385 Legal stuff 386 ----------- 387 388 **Note:** Each source file must include a license header for the Apache 389 Software License 2.0. See the template of the `license header 390 <https://github.com/hyperledger/fabric/blob/master/docs/source/dev-setup/headers.txt>`__. 391 392 We have tried to make it as easy as possible to make contributions. This 393 applies to how we handle the legal aspects of contribution. We use the 394 same approach—the `Developer's Certificate of Origin 1.1 395 (DCO) <https://github.com/hyperledger/fabric/blob/master/docs/source/DCO1.1.txt>`__—that the Linux® Kernel 396 `community <https://elinux.org/Developer_Certificate_Of_Origin>`__ uses 397 to manage code contributions. 398 399 We simply ask that when submitting a patch for review, the developer 400 must include a sign-off statement in the commit message. 401 402 Here is an example Signed-off-by line, which indicates that the 403 submitter accepts the DCO: 404 405 :: 406 407 Signed-off-by: John Doe <john.doe@example.com> 408 409 You can include this automatically when you commit a change to your 410 local git repository using ``git commit -s``. 411 412 Related Topics 413 -------------- 414 415 .. toctree:: 416 :maxdepth: 1 417 418 MAINTAINERS 419 jira_navigation 420 dev-setup/devenv 421 dev-setup/build 422 testing 423 style-guides/go-style 424 425 .. Licensed under Creative Commons Attribution 4.0 International License 426 https://creativecommons.org/licenses/by/4.0/