You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

179 lines
6.7 KiB

  1. // This file is part of the Doxygen Developer Manual
  2. /** @page patchguide Patch Guidelines
  3. \attention If you're behind a corporate wall with http only access to the
  4. world, you can still use these instructions!
  5. \attention You can't send patches to the mailing list anymore at all. Nowadays
  6. you are expected to send patches to the OpenOCD Gerrit GIT server for a
  7. review.
  8. @section gerrit Submitting patches to the OpenOCD Gerrit server
  9. OpenOCD is to some extent a "self service" open source project, so to
  10. contribute, you must follow the standard procedures to have the best
  11. possible chance to get your changes accepted.
  12. The procedure to create a patch is essentially:
  13. - make the changes
  14. - create a commit
  15. - send the changes to the Gerrit server for review
  16. - correct the patch and re-send it according to review feedback
  17. Your patch (or commit) should be a "good patch": focus it on a single
  18. issue, and make it be easily reviewable. Don't make
  19. it so large that it's hard to review; split large
  20. patches into smaller ones. (That can also help
  21. track down bugs later on.) All patches should
  22. be "clean", which includes preserving the existing
  23. coding style and updating documentation as needed.
  24. Say in the commit message if it's a bugfix (describe the bug) or a new
  25. feature. Don't expect patches to merge immediately
  26. for the next release. Be ready to rework patches
  27. in response to feedback.
  28. Add yourself to the GPL copyright for non-trivial changes.
  29. @section stepbystep Step by step procedure
  30. -# Create a Gerrit account at:
  31. - On subsequent sign ins, use the full URL prefaced with 'http://'
  32. For example:
  33. -# Add a username to your profile.
  34. After creating the Gerrit account and signing in, you will need to
  35. add a username to your profile. To do this, go to 'Settings', and
  36. add a username of your choice.
  37. Your username will be required in step 3 and substituted wherever
  38. the string 'USERNAME' is found.
  39. -# Create an SSH public key following the directions on github:
  40. . You can skip step 3
  41. (adding key to Github account) and 4 (testing) - these are useful only if
  42. you actually use Github or want to test whether the new key works fine.
  43. -# Add this new SSH key to your Gerrit account:
  44. go to 'Settings' > 'SSH Public Keys', paste the contents of
  45. ~/.ssh/ into the text field (if it's not visible click on
  46. 'Add Key ...' button) and confirm by clicking 'Add' button.
  47. -# Clone the git repository, rather than just download the source:
  48. @code
  49. git clone git:// openocd
  50. @endcode
  51. or if you have problems with the "git:" protocol, use
  52. the slower http protocol:
  53. @code
  54. git clone openocd
  55. @endcode
  56. -# Set up Gerrit with your local repository. All this does it
  57. to instruct git locally how to send off the changes.
  58. -# Add a new remote to git using Gerrit username:
  59. @code
  60. git remote add review ssh://
  61. git config HEAD:refs/publish/master
  62. @endcode
  63. Or with http only:
  64. @code
  65. git remote add review
  66. git config HEAD:refs/publish/master
  67. @endcode
  68. The http password is configured from your gerrit settings -
  69. \note If you want to simplify http access you can also add your http password to the url as follows:
  70. @code
  71. git remote add review
  72. @endcode
  73. -# You will need to install this hook, we will look into a better solution:
  74. @code
  75. scp -p -P 29418 .git/hooks/
  76. @endcode
  77. Or with http only:
  78. @code
  79. wget
  80. mv commit-msg .git/hooks
  81. chmod +x .git/hooks/commit-msg
  82. @endcode
  83. \note A script exists to simplify the two items above. execute:
  84. @code
  85. tools/ <username>
  86. @endcode
  87. With @<username@> being your Gerrit username.
  88. -# Set up git with your name and email:
  89. @code
  90. git config --global "John Smith"
  91. git config --global ""
  92. @endcode
  93. -# Work on your patches. Split the work into
  94. multiple small patches that can be reviewed and
  95. applied seperately and safely to the OpenOCD
  96. repository.
  97. @code
  98. while(!done) {
  99. work - edit files using your favorite editor.
  100. run "git commit -s -a" to commit all changes.
  101. run tools/ to verify your patch style is ok.
  102. }
  103. @endcode
  104. \note use "git add ." before commit to add new files.
  105. Comment template, notice the short first line w/topic. The topic field
  106. should identify the main part or subsystem the patch touches. Check
  107. git log for examples.
  108. @code
  109. topic: Short comment
  110. <blank line>
  111. Longer comments over several lines, explaining (where applicable) the
  112. reason for the patch and the general idea the solution is based on,
  113. any major design decisions, etc...
  114. <blank line>
  115. Signed-off-by: ...
  116. @endcode
  117. -# Next you need to make sure that your patches
  118. are on top of the latest stuff on the server and
  119. that there are no conflicts:
  120. @code
  121. git pull --rebase origin master
  122. @endcode
  123. -# Send the patches to the Gerrit server for review:
  124. @code
  125. git push review
  126. @endcode
  127. -# Forgot something, want to add more? Just make the changes and do:
  128. @code
  129. git commit --amend
  130. git push review
  131. @endcode
  132. Further reading:
  133. @section timeline When can I expect my contribution to be committed?
  134. The code review is intended to take as long as a week or two to allow
  135. maintainers and contributors who work on OpenOCD only in their spare
  136. time oportunity to perform a review and raise objections.
  137. With Gerrit much of the urgency of getting things committed has been
  138. removed as the work in progress is safely stored in Gerrit and
  139. available if someone needs to build on your work before it is
  140. submitted to the official repository.
  141. Another factor that contributes to the desire for longer cool-off
  142. times (the time a patch lies around without any further changes or
  143. comments), it means that the chances of quality regression on the
  144. master branch will be much reduced.
  145. If a contributor pushes a patch, it is considered good form if another
  146. contributor actually approves and submits that patch.
  147. It should be noted that a negative review in Gerrit ("-1" or "-2") may (but does
  148. not have to) be disregarded if all conditions listed below are met:
  149. - the concerns raised in the review have been addressed (or explained),
  150. - reviewer does not re-examine the change in a month,
  151. - reviewer does not answer e-mails for another month.
  152. @section browsing Browsing Patches
  153. All OpenOCD patches can be reviewed <a href="">here</a>.
  154. */
  155. /** @file
  156. This file contains the @ref patchguide page.
  157. */