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.

243 lines
9.3 KiB

  1. // This file is part of the Doxygen Developer Manual
  2. /** @page patchguide Patch Guidelines
  3. \attention You can't send patches to the mailing list anymore at all. Nowadays
  4. you are expected to send patches to the OpenOCD Gerrit GIT server for a
  5. review.
  6. \attention If you already have a Gerrit account and want to try a
  7. different sign in method, please first sign in as usually, press your
  8. name in the upper-right corner, go to @a Settings, select @a
  9. Identities pane, press <em>Link Another Identity</em> button. In case
  10. you already have duplicated accounts, ask administrators for manual
  11. merging.
  12. \attention If you're behind a corporate wall with http only access to the
  13. world, you can still use these instructions!
  14. @section gerrit Submitting patches to the OpenOCD Gerrit server
  15. OpenOCD is to some extent a "self service" open source project, so to
  16. contribute, you must follow the standard procedures to have the best
  17. possible chance to get your changes accepted.
  18. The procedure to create a patch is essentially:
  19. - make the changes
  20. - create a commit
  21. - send the changes to the Gerrit server for review
  22. - correct the patch and re-send it according to review feedback
  23. Your patch (or commit) should be a "good patch": focus it on a single
  24. issue, and make it easily reviewable. Don't make
  25. it so large that it's hard to review; split large
  26. patches into smaller ones (this will also help
  27. to track down bugs later). All patches should
  28. be "clean", which includes preserving the existing
  29. coding style and updating documentation as needed. When adding a new
  30. command, the corresponding documentation should be added to
  31. @c doc/openocd.texi in the same commit. OpenOCD runs on both Little
  32. Endian and Big Endian hosts so the code can't count on specific byte
  33. ordering (in other words, must be endian-clean).
  34. There are several additional methods of improving the quality of your
  35. patch:
  36. - Runtime testing with Valgrind Memcheck
  37. This helps to spot memory leaks, undefined behaviour due to
  38. uninitialized data or wrong indexing, memory corruption, etc.
  39. - Clang Static Analyzer
  40. Using this tool uncovers many different kinds of bugs in C code,
  41. with problematic execution paths fully explained. It is a part of
  42. standard Clang installation.
  43. To generate a report, run this in the OpenOCD source directory:
  44. @code
  45. mkdir build-scanbuild; cd build-scanbuild
  46. scan-build ../configure
  47. scan-build make CFLAGS="-std=gnu99 -I. -I../../jimtcl"
  48. @endcode
  49. - Runtime testing with sanitizers
  50. Both GCC and LLVM/Clang include advanced instrumentation options to
  51. detect undefined behaviour and many kinds of memory
  52. errors. Available with @c -fsanitize=* command arguments.
  53. Example usage:
  54. @code
  55. mkdir build-sanitizers; cd build-sanitizers
  56. ../configure CC=clang CFLAGS="-fno-omit-frame-pointer \
  57. -fsanitize=address -fsanitize=undefined -ggdb3"
  58. make
  59. export ASAN_OPTIONS=detect_stack_use_after_return=1
  60. src/openocd -s ../tcl -f /path/to/openocd.cfg
  61. @endcode
  62. Please consider performing these additional checks where appropriate
  63. (especially Clang Static Analyzer for big portions of new code) and
  64. mention the results (e.g. "Valgrind-clean, no new Clang analyzer
  65. warnings") in the commit message.
  66. Say in the commit message if it's a bugfix (describe the bug) or a new
  67. feature. Don't expect patches to merge immediately
  68. for the next release. Be ready to rework patches
  69. in response to feedback.
  70. Add yourself to the GPL copyright for non-trivial changes.
  71. @section stepbystep Step by step procedure
  72. -# Create a Gerrit account at:
  73. - On subsequent sign ins, use the full URL prefaced with 'http://'
  74. For example:
  75. -# Add a username to your profile.
  76. After creating the Gerrit account and signing in, you will need to
  77. add a username to your profile. To do this, go to 'Settings', and
  78. add a username of your choice.
  79. Your username will be required in step 3 and substituted wherever
  80. the string 'USERNAME' is found.
  81. -# Create an SSH public key following the directions on github:
  82. . You can skip step 3
  83. (adding key to Github account) and 4 (testing) - these are useful only if
  84. you actually use Github or want to test whether the new key works fine.
  85. -# Add this new SSH key to your Gerrit account:
  86. go to 'Settings' > 'SSH Public Keys', paste the contents of
  87. ~/.ssh/ into the text field (if it's not visible click on
  88. 'Add Key ...' button) and confirm by clicking 'Add' button.
  89. -# Clone the git repository, rather than just download the source:
  90. @code
  91. git clone git:// openocd
  92. @endcode
  93. or if you have problems with the "git:" protocol, use
  94. the slower http protocol:
  95. @code
  96. git clone openocd
  97. @endcode
  98. -# Set up Gerrit with your local repository. All this does it
  99. to instruct git locally how to send off the changes.
  100. -# Add a new remote to git using Gerrit username:
  101. @code
  102. git remote add review ssh://
  103. git config HEAD:refs/for/master
  104. @endcode
  105. Or with http only:
  106. @code
  107. git remote add review
  108. git config HEAD:refs/for/master
  109. @endcode
  110. The http password is configured from your gerrit settings -
  111. \note If you want to simplify http access you can also add your http password to the url as follows:
  112. @code
  113. git remote add review
  114. @endcode
  115. \note All contributions should be pushed to @c refs/for/master on the
  116. Gerrit server, even if you plan to use several local branches for different
  117. topics. It is possible because @c for/master is not a traditional Git
  118. branch.
  119. -# You will need to install this hook, we will look into a better solution:
  120. @code
  121. scp -p -P 29418 .git/hooks/
  122. @endcode
  123. Or with http only:
  124. @code
  125. wget
  126. mv commit-msg .git/hooks
  127. chmod +x .git/hooks/commit-msg
  128. @endcode
  129. \note A script exists to simplify the two items above. Execute:
  130. @code
  131. tools/ <username>
  132. @endcode
  133. With @<username@> being your Gerrit username.
  134. -# Set up git with your name and email:
  135. @code
  136. git config --global "John Smith"
  137. git config --global ""
  138. @endcode
  139. -# Work on your patches. Split the work into
  140. multiple small patches that can be reviewed and
  141. applied separately and safely to the OpenOCD
  142. repository.
  143. @code
  144. while(!done) {
  145. work - edit files using your favorite editor.
  146. run "git commit -s -a" to commit all changes.
  147. run tools/ to verify your patch style is ok.
  148. }
  149. @endcode
  150. \note use "git add ." before commit to add new files.
  151. Comment template, notice the short first line w/topic. The topic field
  152. should identify the main part or subsystem the patch touches. Check
  153. git log for examples.
  154. @code
  155. topic: Short comment
  156. <blank line>
  157. Longer comments over several lines, explaining (where applicable) the
  158. reason for the patch and the general idea the solution is based on,
  159. any major design decisions, etc...
  160. <blank line>
  161. Signed-off-by: ...
  162. @endcode
  163. -# Next you need to make sure that your patches
  164. are on top of the latest stuff on the server and
  165. that there are no conflicts:
  166. @code
  167. git pull --rebase origin master
  168. @endcode
  169. -# Send the patches to the Gerrit server for review:
  170. @code
  171. git push review
  172. @endcode
  173. -# Forgot something, want to add more? Just make the changes and do:
  174. @code
  175. git commit --amend
  176. git push review
  177. @endcode
  178. Further reading:
  179. @section timeline When can I expect my contribution to be committed?
  180. The code review is intended to take as long as a week or two to allow
  181. maintainers and contributors who work on OpenOCD only in their spare
  182. time opportunity to perform a review and raise objections.
  183. With Gerrit much of the urgency of getting things committed has been
  184. removed as the work in progress is safely stored in Gerrit and
  185. available if someone needs to build on your work before it is
  186. submitted to the official repository.
  187. Another factor that contributes to the desire for longer cool-off
  188. times (the time a patch lies around without any further changes or
  189. comments), it means that the chances of quality regression on the
  190. master branch will be much reduced.
  191. If a contributor pushes a patch, it is considered good form if another
  192. contributor actually approves and submits that patch.
  193. It should be noted that a negative review in Gerrit ("-1" or "-2") may (but does
  194. not have to) be disregarded if all conditions listed below are met:
  195. - the concerns raised in the review have been addressed (or explained),
  196. - reviewer does not re-examine the change in a month,
  197. - reviewer does not answer e-mails for another month.
  198. @section browsing Browsing Patches
  199. All OpenOCD patches can be reviewed <a href="">here</a>.
  200. @section reviewing Reviewing Patches
  201. From the main <a href=",n,z">Review
  202. page</a> select the patch you want to review and click on that patch. On the
  203. appearing page select the download method (top right). Apply the
  204. patch. After building and testing you can leave a note with the "Reply"
  205. button and mark the patch with -1, 0 and +1.
  206. */
  207. /** @file
  208. This file contains the @ref patchguide page.
  209. */