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.

224 lines
8.5 KiB

  1. /** @page primerpatches Patch Primer
  2. This page provides an introduction to patching that may be useful
  3. for OpenOCD contributors who are unfamiliar with the process.
  4. @section primerpatchintro Introduction to Patching
  5. The standard method for creating patches requires developers to:
  6. - checkout the Subversion repository (or bring a copy up-to-date),
  7. - make the necessary modifications to a working copy,
  8. - check with 'svn status' to see which files will be modified/added, and
  9. - use 'svn diff' to review the changes and produce a patch.
  10. It is important to minimize the changes to only those lines that contain
  11. important differences; do not allow stray whitespace changes into your
  12. patches, and keep the focus to a single logical change.
  13. @section primerpatchcreate Creating Patches
  14. You can create a patch (from the root of your working copy) with a
  15. command like the following example: @par
  16. @verbatim
  17. svn diff > patch-name.patch
  18. @endverbatim
  19. where @a patch-name should be something that is descriptive and unique.
  20. The above command will create a patch containing all of the changes in
  21. the working copy; if you want to obtain a subset, simply provide the
  22. list of files to the command: @par
  23. @verbatim
  24. svn diff doc > <patch-name>-doc.patch
  25. svn diff src > <patch-name>-src.patch
  26. @endverbatim
  27. This will create two patches, each containing only those changes present
  28. in the subdirectory specified.
  29. @subsection primerpatchcreate Naming Patches
  30. One developer has evolved an informal standard for naming his patches: @par
  31. @verbatim
  32. <project>-<lod>-<action>-<task>.patch
  33. @endverbatim
  34. where @a project is @c openocd, @a lod (line-of-development) could be a
  35. subsystem (e.g. @c jtag, @c jlink, etc.) or other group identifier,
  36. @a action is @c add, @c change, @c fix, @c update, etc., and @a task is
  37. whatever the patch will accomplish (in 2-4 words).
  38. This scheme does not need to be followed, but it is helpful for
  39. maintainers that receive many patches. You do not want your own
  40. @c openocd.patch file to be accidentally overwritten by another
  41. submission, sending your patch to the bit bucket on accident.
  42. @section primerpatchpreflight Developer Review
  43. Before sending in patches, please make sure you have updated to the
  44. latest version of the trunk (using <code>svn up</code>) before creating
  45. your patch. This helps to increase the chances that it will apply
  46. cleanly to the trunk. However, the content matters most.
  47. When creating a patch using "<code>svn diff</code>", Subversion will
  48. produce a patch that contains all of the changes in your working copy.
  49. To manage multiple changes at once, you either need one working copy per
  50. patch, or you can specified specific files and directories when using
  51. <code>svn diff</code>. Overlapping patches will be discussed in the
  52. next section.
  53. The remainder of this section provides
  54. @subsection primerpatchprops Subversion Properties
  55. The Subversion attributes of files can be examined with commands like the
  56. following: @par
  57. @verbatim
  58. $ svn pl README
  59. Properties on 'README':
  60. svn:eol-style
  61. $ svn pl tools/rlink_make_speed_table/
  62. Properties on 'tools/rlink_make_speed_table/':
  63. svn:executable
  64. svn:eol-style
  65. $
  66. @endverbatim
  67. @subsection primerpatchpropcrlf Native Line-endings
  68. Subversion checks out files marked with the attribute @c svn:eol-style
  69. set to @c native such that these files contain the default line ending
  70. style of the current host ('\\n' or '\\r\\n'). By using the proper line
  71. endings for different platforms, two different byte streams for the same
  72. file will be produced.
  73. @subsection primerpatchwincrlf Windows Patching Problems
  74. Because of the line-ending functionality, it may be correct when a fresh
  75. patch does not apply cleanly on the Windows platform. This is because
  76. patches are created by SVN with UNIX line endings, so the context and
  77. changes will not appear to match the files with Windows line endings.
  78. In other words, the following command may @b not succeed because @c foo
  79. has its @c svn:eol-style property set to @c native: @par
  80. @code
  81. svn diff foo | patch -R
  82. @endcode
  83. The following series of commands will work: @par
  84. @code
  85. svn diff foo | unix2dos | patch -R
  86. @endcode
  87. This is not a bug.
  88. @todo Does Subversion's treatment of line-endings for files marked with
  89. svn:eol-style=native continue to pose the problems described here, or
  90. has this been magically solved?
  91. @section primerpatchseries Patch Series
  92. As was mentioned above, each patch should contain one logical @c task,
  93. and multiple logical tasks should be split into a series of patches.
  94. There are no hard guidelines for how that is to be done; it's an art
  95. form. Many simple changes should not have to worry about being split,
  96. as they will naturally represent a single task.
  97. When working on several different non-intersecting lines of development,
  98. a combination of multiple working copies and patch series management
  99. techniques can become critical to efficiently managing change. This
  100. again is an area where developers have favorite methodologies that are
  101. simply a matter of taste or familiarity; your mileage may vary.
  102. Packages such as @c patchutils, @c diffutils, and @c quilt are among
  103. those that have proved themselves invaluable for these type of tasks.
  104. Others take their patch management a step further, tracking the
  105. Subversion repository with git-svn and employing GIT conventions and
  106. methodologies for development.
  107. @subsection primerpatchseriesinterdiff Using @c interdiff
  108. The @c patchutils package includes the @c interdiff command, which
  109. produces a patch that contains the changes made between two other
  110. patches. This command can be used to manage the creation of trivial
  111. patch series. For example, the following sequence of commands will
  112. produce three patches: @par
  113. @verbatim
  114. $ cd openocd-head/
  115. $ svn up && svn st
  116. At revision NNNN.
  117. $ <<<start changes for patch #1>>>
  118. ...
  119. $ <<<finish changes for patch #1>>>
  120. $ svn diff > series-1.patch # patch #1 is easy
  121. $ <<<start changes for patch #2>>>
  122. ...
  123. $ <<<finish changes for patch #2>>>
  124. $ svn diff > series-1+2.patch # create patch 1+2
  125. $ interdiff series-1{,+2}.patch > series-2.patch # 1 ~ 1+2 => #2
  126. $ <<<start changes for patch #3>>>
  127. ...
  128. $ <<<finish changes for patch #3>>>
  129. $ svn diff > series-1+2+3.patch # create patch 1+2+3
  130. $ interdiff series-1+2{,+3}.patch > series-3.patch # 1+2 ~ 1+2+3 => 3
  131. @endverbatim
  132. This technique falls apart when the repository changes, but this may be
  133. suitable for small series of patches.
  134. @subsection primerpatchseriesquilt Using @c quilt
  135. The @c quilt package provides scripts to manage series of patches more
  136. efficiently than can be managed by hand. For out-of-tree work projects
  137. that require such patch management, @c quilt provides an indispensable
  138. tool for solving the problem.
  139. @subsection primerpatchseriesgit Using @c git
  140. The @c git revision control system provides a tool for tracking
  141. Subversion repositories.
  142. @section primerpatchsubmit Submitting Patches
  143. Write access to the OpenOCD Subversion repository is limited to
  144. contributors that have demonstrated the ability to produce clear,
  145. consistent, and frequent patches. These individuals are responsible
  146. for maintaining the integrity of the repository for the community.
  147. Thus, commits to the Subversion repository must be handled by one of
  148. these maintainers.
  149. Patches must be sent to the OpenOCD developer mailing list:
  150. @par
  152. They will be reviewed and committed if the changes are found to be
  153. acceptable. If there are problems, you will receive feedback via the
  154. mailing list; in general, the maintainers prefer all communication to go
  155. through the list, as the entire community needs to judge contributions
  156. for possible merits and mistakes.
  157. Contributors may be asked to address certain issues and submit a new
  158. patch. In the event that it gets overlooked, you may need to resubmit
  159. it or prompt for feedback. Please have patience, as many maintainers
  160. work on the project voluntarily and without compensation for the time
  161. that they spend doing these tasks.
  162. @section primerpatchguide Guidelines for Submitting Patches
  163. - Each patch file should contain:
  164. - A commit description that describes all of the changes.
  165. - A separator line that contains three hyphens: <code>---</code>
  166. - A summary of the changes produced by diffstat (optional)
  167. - Another separator line (optional)
  168. - The actual patch contents, containing a single change.
  169. - Each patch series should include:
  170. - A summary of the patches in the series.
  171. - Logically-related patches that contain incremental changes.
  172. */
  173. /** @file
  174. This file contains the @ref primerpatches page.
  175. */