Debian Codegraph @

SubmittingPatches

raw
1 This is a guide to submitting patches to the concordance project.
2
3 TABLE OF CONTENTS
4 1. Preparing a change
5 2. Generating patches
6 3. Preparing and submitting your patch
7 4. Additional notes for major changes
8 5. A word on comments
9
10
11 PREPARING A CHANGE
12
13 If you would like to make a change to the codebase, you need to decide if this
14 is a major change or a minor change. Major changes include anything that
15 affects the API, ABI, anything that affects lots of files, adds/removes
16 classes, etc.
17
18 If your plan is to make a major change, then you should send a description of
19 the changes you plan to make to the concordance-devel list FIRST. By doing
20 this you give the developers a chance to comment on your plan and provide
21 suggestions and guidance before you invest the time. This will save you time
22 and effort and provide a much higher chance of your patch being accepted. Also
23 see "ADDITIONAL NOTES FOR MAJOR CHANGES" below.
24
25 If your plan is to make a minor change, you are still welcome to send an email
26 before you start to the list, but it's not as big of a deal.
27
28
29 GENERATING PATCHES
30
31 After making your changes, you should always make sure you have done a 'cvs
32 update' to ensure you'll be generating your patch against the latest CVS
33 sources.
34
35 Patches should always be generated via CVS's diff, and from top-level CVS
36 directory. Additionally, they should always be in unified diff format ("-u"),
37 should show new/removed files ("-N"), be recursive ("-R"), and use the -p flag
38 to make sure the C function name is included for all changes. For example:
39
40 CVSTREE=~/cvs/concordance
41 cd $CVSTREE
42 vi libconcord/remote.cpp
43 cvs diff -NRup >/tmp/libconcord_remote.patch
44
45 You should ALWAYS read your patch through after generating it to make sure it
46 contains the changes you expect and ONLY the changes you expect.
47
48 You should ensure the following:
49 1. You've maintained the same coding style. See the CodingStyle document
50 in this directory.
51 2. You should make sure that your code is properly commented.
52
53
54 PREPARING AND SUBMITTING YOUR PATCH
55
56 Your patch should be sent in as an attachement. Mail clients often wrap emails
57 (and rightly so!) which can break a patch. Attach your patch to your email.
58
59 The body of your email should have a good descriptiong of your patch. The more
60 far-reaching your patch is, the more detailed your description should be.
61
62 A good description includes justifying any ABI/API changes, an explanation of
63 the goal and outcome of the patch, and a list of changes by file, where
64 appropriate.
65
66 The subject of an email SHOULD start with "PATCH: " and include a _useful_
67 description of your patch. Where possible, include the component affected
68 (concordance vs. libconcord) GOOD examples include:
69
70 PATCH: concordance: fix double-free bug
71 PATCH: libconcord: Add remote_info table entry for 4847 byte location
72
73 BAD examples include:
74
75 PATCH: update
76 PATCH: libconcord fix
77 PATCH: new remote
78
79 NOTE: PATCHES SHOULD ALWAYS BE SENT TO THE -devel LIST! Even if you are
80 attaching a patch to a bug, you should still send it to the devel list if you
81 want it committed.
82
83
84 PATCHSET SUBMISSIONS
85
86 Sometimes it makes sense to break a given change into several pieces, but you
87 still want to submit them together. In this case, you may do this in two ways.
88 You could just you attach all patches to a single email with useful filenames
89 like 1_update_foo_API.patch 2_update_bar_API and a list of the patches and
90 their details in the email.
91
92 Alternatively, if you prefer multiple emails, you can send a group of emails
93 as follows.
94
95 An initial email with a subject that starts with "[PATCH 0/X]" (where X is the
96 total number of patches) and a short description should be sent. This email
97 should contain all the information about the patchset as a whole, as well as a
98 list of patch-containing-emails that will follow. This list should look like
99 this:
100
101 1/2 - libconcord: update foo() API to accept new parameter
102 2/2 - concordance: use new foo() paremeter to do bar
103
104 Assuming here that X is 2. Then these patches should be submitted with
105 subjects like: "[PATCH 1/2] libconcord: update foo() API to accept new param."
106
107 Note that if there's a possiblity of merging some parts of your patchset in
108 stages, then they should definitely be split into multiple emails.
109
110
111 ADDITIONAL NOTES FOR MAJOR CHANGES
112
113 As previously mentioned, all major changes should be mentioned on the list.
114 Note, however, that changes to the ABI or API need to be justified. The API,
115 in particular, should change as little as possible.
116
117 If a change to the API is needed, remember that the API is *C* API even though
118 the library itself is written in C++. Any changes to the API must ensure it's
119 still C-compatible, and that all of the API is exported properly for C
120 clients.
121
122 In addition, all API changes must be added to all bindings we support as well.
123 If you don't have experience with some of the languages, we can help.
124
125 A WORD ON COMMENTS
126 Comments should be immediately above the block of code they are explaining,
127 NOT next to it. For example, we prefer this:
128
129 /*
130 * This special algorith for XXX does A, then B, then C, then D.
131 * It is necessary because of bar.
132 */
133 if (foo) {
134 ...
135 }
136
137 Not this:
138
139 if (foo) {
140 a = *(b+8); // Some comment here
141
142 In addition, comments should explain code, not just narrate it. A comments
143 that says "skip the first byte" isn't useful, but a comment that says "the
144 first byte is all 0 for Windows, so we skip it when not in Windows" is very
145 useful.
146
147
148
149
150
151
152
153
154
155 # for vim to text-wrap
156 vim:textwidth=78:
157