cb3c07c292933dfbb7568c61400781e41b6dbee2
[openocd.git] / 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 git repository (or bring a copy up-to-date),
10 - make the necessary modifications to a working copy,
11 - check with 'git status' to see which files will be modified/added, and
12 - use 'git 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 git 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 git diff doc > <patch-name>-doc.patch
33 git 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>git pull</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>git diff</code>", git 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>git diff</code>.  Overlapping patches will be discussed in the
68 next section.
69
70 @todo Does git's treatment of line-endings behave sanely?
71 Basically, the repository should use newlines internally,
72 and convert to/from CRLF on Windows etc.
73
74 @section primerpatchseries Patch Series
75
76 As was mentioned above, each patch should contain one logical @c task,
77 and multiple logical tasks should be split into a series of patches.
78 There are no hard guidelines for how that is to be done; it's an art
79 form.  Many simple changes should not have to worry about being split,
80 as they will naturally represent a single task.
81
82 When working on several different non-intersecting lines of development,
83 a combination of multiple working copies and patch series management
84 techniques can become critical to efficiently managing change.  This
85 again is an area where developers have favorite methodologies that are
86 simply a matter of taste or familiarity; your mileage may vary.
87
88 Packages such as @c patchutils, @c diffutils, and @c quilt are among
89 those that have proved themselves invaluable for these type of tasks.
90 Others take their patch management a step further, using stkgit or
91 some other framework on top of git.
92
93 @subsection primerpatchseriesinterdiff Using @c interdiff
94
95 The @c patchutils package includes the @c interdiff command, which
96 produces a patch that contains the changes made between two other
97 patches.  This command can be used to manage the creation of trivial
98 patch series.  For example, the following sequence of commands will
99 produce three patches: @par
100 @verbatim
101 $ cd openocd/
102 $ git pull
103 ...
104 $ <<<start changes for patch #1>>>
105 ...
106 $ <<<finish changes for patch #1>>>
107 $ git diff > series-1.patch                         # patch #1 is easy
108 $ <<<start changes for patch #2>>>
109 ...
110 $ <<<finish changes for patch #2>>>
111 $ git diff > series-1+2.patch                       # create patch 1+2
112 $ interdiff series-1{,+2}.patch > series-2.patch    #   1 ~  1+2  => #2
113 $ <<<start changes for patch #3>>>
114 ...
115 $ <<<finish changes for patch #3>>>
116 $ git diff > series-1+2+3.patch                     # create patch 1+2+3
117 $ interdiff series-1+2{,+3}.patch > series-3.patch  # 1+2 ~ 1+2+3 => 3
118 @endverbatim
119
120 This technique falls apart when the repository changes, but this may be
121 suitable for small series of patches.
122
123 @subsection primerpatchseriesquilt Using @c quilt
124
125 The @c quilt package provides scripts to manage series of patches more
126 efficiently than can be managed by hand.  For out-of-tree work projects
127 that require such patch management, @c quilt provides an indispensable
128 tool for solving the problem.
129
130 @section primerpatchsubmit Submitting Patches
131
132 Write access to the OpenOCD git repository is limited to
133 contributors that have demonstrated the ability to produce clear,
134 consistent, and frequent patches.  These individuals are responsible
135 for maintaining the integrity of the repository for the community.
136
137 Thus, commits to the git repository must be handled by one of
138 these maintainers.
139
140 Patches must be sent to the OpenOCD developer mailing list:
141 @par
142         openocd-devel@lists.sourceforge.net
143
144 They will be reviewed and committed if the changes are found to be
145 acceptable.  If there are problems, you will receive feedback via the
146 mailing list; in general, the maintainers prefer all communication to go
147 through the list, as the entire community needs to judge contributions
148 for possible merits and mistakes.
149
150 Contributors may be asked to address certain issues and submit a new
151 patch.  In the event that it gets overlooked, you may need to resubmit
152 it or prompt for feedback.  Please have patience, as many maintainers
153 work on the project voluntarily and without compensation for the time
154 that they spend doing these tasks.
155
156 @section primerpatchguide Guidelines for Submitting Patches
157
158 - Each patch file should contain:
159   - A commit description that describes all of the changes.
160   - A separator line that contains three hyphens: <code>---</code>
161   - A summary of the changes produced by diffstat (optional)
162   - Another separator line (optional)
163   - The actual patch contents, containing a single change.
164
165 - Each patch series should include:
166   - A summary of the patches in the series.
167   - Logically-related patches that contain incremental changes.
168
169  */
170 /** @file
171 This file contains the @ref primerpatches page.
172 */