doc/manual/primer/patches.txt

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