blob: db89ef7bc1c2228ff79d5041cc9af7895d9d03e8 [file] [log] [blame]
Willy Tarreau09e0d742019-06-15 17:15:12 +02001 HOW TO GET YOUR CODE ACCEPTED IN HAPROXY
2 READ THIS CAREFULLY BEFORE SUBMITTING CODE
Willy Tarreau11e334d92015-09-20 22:31:42 +02003
4THIS DOCUMENT PROVIDES SOME RULES TO FOLLOW WHEN SENDING CONTRIBUTIONS. PATCHES
Willy Tarreau09e0d742019-06-15 17:15:12 +02005NOT FOLLOWING THESE RULES WILL SIMPLY BE IGNORED IN ORDER TO PROTECT ALL OTHER
Willy Tarreau11e334d92015-09-20 22:31:42 +02006RESPECTFUL CONTRIBUTORS' VALUABLE TIME.
7
8
Willy Tarreau09e0d742019-06-15 17:15:12 +02009Abstract
10--------
11
12If you have never contributed to HAProxy before, or if you did so and noticed
13that nobody seems to be interested in reviewing your submission, please do read
14this long document carefully. HAProxy maintainers are particularly demanding on
15respecting certain simple rules related to general code and documentation style
16as well as splitting your patches and providing high quality commit messages.
17The reason behind this is that your patch will be met multiple times in the
18future, when doing some backporting work or when bisecting a bug, and it is
19critical that anyone can quickly decide if the patch is right, wrong, if it
20misses something, if it must be reverted or needs to be backported. Maintainers
21are generally benevolent with newcomers and will help them provided their work
22indicates they have at least read this document. Some have improved over time,
23to the point of being totally trusted and gaining commit access so they don't
24need to depend on anyone to pick their code. On the opposite, those who insist
25not making minimal efforts however will simply be ignored.
26
27
Willy Tarreau11e334d92015-09-20 22:31:42 +020028Background
29----------
30
Willy Tarreau09e0d742019-06-15 17:15:12 +020031HAProxy is a community-driven project. But like most highly technical projects
32it takes a lot of time to develop the skills necessary to be autonomous in the
33project, and there is a very small core team helped by a small set of very
34active participants. While most of the core team members work on the code as
35part of their day job, most participants do it on a voluntary basis during
Tim Duesterhus2847f142019-06-15 19:47:29 +020036their spare time. The ideal model for developers is to spend their time:
Willy Tarreau09e0d742019-06-15 17:15:12 +020037 1) developing new features
38 2) fixing bugs
39 3) doing maintenance backports
40 4) reviewing other people's code
41
42It turns out that on a project like HAProxy, like many other similarly complex
Tim Duesterhus2847f142019-06-15 19:47:29 +020043projects, the time spent is exactly the opposite:
44 1) reviewing other people's code
Willy Tarreau09e0d742019-06-15 17:15:12 +020045 2) doing maintenance backports
46 3) fixing bugs
47 4) developing new features
48
49A large part of the time spent reviewing code often consists in giving basic
50recommendations that are already explained in this file. In addition to taking
51time, it is not appealing for people willing to spend one hour helping others
52to do the same thing over and over instead of discussing the code design, and
53it tends to delay the start of code reviews.
Willy Tarreau11e334d92015-09-20 22:31:42 +020054
Willy Tarreau09e0d742019-06-15 17:15:12 +020055Regarding backports, they are necessary to provide a set of stable branches
56that are deployed in production at many places. Load balancers are complex and
57new features often induce undesired side effects in other areas, which we will
58call bugs. Thus it's common for users to stick to a branch featuring everything
59they need and not to upgrade too often. This backporting job is critical to the
60ecosystem's health and must be done regularly. Very often the person devoting
61some time on backports has little to no information about the relevance (let
62alone importance) of a patch and is unlikely to be an expert in the area
63affected by the patch. It's the role of the commit message to explain WHAT
64problem the patch tries to solve, WHY it is estimated that it is a problem, and
65HOW it tries to address it. With these elements, the person in charge of the
66backports can decide whether or not to pick the patch. And if the patch does
67not apply (which is common for older versions) they have information in the
68commit message about the principle and choices that the initial developer made
69and will try to adapt the patch sticking to these principles. Thus, the time
70spent backporting patches solely depends on the code quality and the commit
71message details and accuracy.
72
73When it turns to fixing bugs, before declaring a bug, there is an analysis
74phase. It starts with "is this behaviour expected", "is it normal", "under what
75circumstances does it happen", "when did it start to happen", "was it intended",
76"was it just overlooked", and "how to fix it without breaking the initial
77intent". A utility called "git bisect" is usually involved in determining when
78the behaviour started to happen. It determines the first patch which introduced
79the new behaviour. If the patch is huge, touches many areas, is really difficult
80to read because it needlessly reindents code or adds/removes line breaks out of
81context, it will be very difficult to figure what part of this patch broke the
82behaviour. Then once the part is figured, if the commit message doesn't provide
83a detailed description about the intent of the patch, i.e. the problem it was
84trying to solve, why and how, the developer landing on that patch will really
85feel powerless. And very often in this case, the fix for the problem will break
86something else or something that depended on the original patch.
87
88But contrary to what it could look like, providing great quality patches is not
89difficult, and developers will always help contributors improve their patches
90quality because it's in their interest as well. History has shown that first
91time contributors can provide an excellent work when they have carefully read
92this document, and that people coming from projects with different practices
93can grow from first-time contributor to trusted committer in about 6 months.
94
Willy Tarreau11e334d92015-09-20 22:31:42 +020095
96Preparation
97-----------
98
99It is possible that you'll want to add a specific feature to satisfy your needs
100or one of your customers'. Contributions are welcome, however maintainers are
101often very picky about changes. Patches that change massive parts of the code,
102or that touch the core parts without any good reason will generally be rejected
103if those changes have not been discussed first.
104
105The proper place to discuss your changes is the HAProxy Mailing List. There are
106enough skilled readers to catch hazardous mistakes and to suggest improvements.
107There is no other place where you'll find as many skilled people on the project,
108and these people can help you get your code integrated quickly. You can
109subscribe to it by sending an empty e-mail at the following address :
110
111 haproxy+subscribe@formilux.org
112
Willy Tarreau09e0d742019-06-15 17:15:12 +0200113It is not even necessary to subscribe, you can post there and verify via the
114public list archives that your message was properly delivered. In this case you
115should indicate in your message that you'd like responders to keep you CCed.
116Please visit http://haproxy.org/ to figure available options to join the list.
117
Willy Tarreau11e334d92015-09-20 22:31:42 +0200118If you have an idea about something to implement, *please* discuss it on the
119list first. It has already happened several times that two persons did the same
120thing simultaneously. This is a waste of time for both of them. It's also very
121common to see some changes rejected because they're done in a way that will
122conflict with future evolutions, or that does not leave a good feeling. It's
123always unpleasant for the person who did the work, and it is unpleasant in
Willy Tarreau09e0d742019-06-15 17:15:12 +0200124general because people's time and efforts are valuable and would be better
Willy Tarreau11e334d92015-09-20 22:31:42 +0200125spent working on something else. That would not happen if these were discussed
126first. There is no problem posting work in progress to the list, it happens
Willy Tarreau09e0d742019-06-15 17:15:12 +0200127quite often in fact. Just prefix your mail subject with "RFC" (it stands for
128"request for comments") and everyone will understand you'd like some opinion
129on your work in progress. Also, don't waste your time with the doc when
130submitting patches for review, only add the doc with the patch you consider
131ready to merge (unless you need some help on the doc itself, of course).
Willy Tarreau11e334d92015-09-20 22:31:42 +0200132
Tim Duesterhus2847f142019-06-15 19:47:29 +0200133Another important point concerns code portability. HAProxy requires gcc as the
Willy Tarreau11e334d92015-09-20 22:31:42 +0200134C compiler, and may or may not work with other compilers. However it's known to
135build using gcc 2.95 or any later version. As such, it is important to keep in
136mind that certain facilities offered by recent versions must not be used in the
Tim Duesterhus2847f142019-06-15 19:47:29 +0200137code:
Willy Tarreau11e334d92015-09-20 22:31:42 +0200138
139 - declarations mixed in the code (requires gcc >= 3.x and is a bad practice)
140 - GCC builtins without checking for their availability based on version and
141 architecture ;
142 - assembly code without any alternate portable form for other platforms
143 - use of stdbool.h, "bool", "false", "true" : simply use "int", "0", "1"
144 - in general, anything which requires C99 (such as declaring variables in
145 "for" statements)
146
147Since most of these restrictions are just a matter of coding style, it is
Willy Tarreau09e0d742019-06-15 17:15:12 +0200148normally not a problem to comply. Please read doc/coding-style.txt for all the
149details.
Willy Tarreau11e334d92015-09-20 22:31:42 +0200150
Willy Tarreau9d84cd62017-07-18 06:56:40 +0200151When modifying some optional subsystem (SSL, Lua, compression, device detection
152engines), please make sure the code continues to build (and to work) when these
153features are disabled. Similarly, when modifying the SSL stack, please always
154ensure that supported OpenSSL versions continue to build and to work, especially
155if you modify support for alternate libraries. Clean support for the legacy
156OpenSSL libraries is mandatory, support for its derivatives is a bonus and may
Thayne McCombscdbcca92021-01-07 21:24:41 -0700157occasionally break even though a great care is taken. In other words, if you
Willy Tarreau9d84cd62017-07-18 06:56:40 +0200158provide a patch for OpenSSL you don't need to test its derivatives, but if you
159provide a patch for a derivative you also need to test with OpenSSL.
160
Willy Tarreau11e334d92015-09-20 22:31:42 +0200161If your work is very confidential and you can't publicly discuss it, you can
162also mail willy@haproxy.org directly about it, but your mail may be waiting
Willy Tarreau138544f2017-03-31 16:24:44 +0200163several days in the queue before you get a response, if you get a response at
164all. Retransmit if you don't get a response by one week. Please note that
165direct sent e-mails to this address for non-confidential subjects may simply
Willy Tarreau09e0d742019-06-15 17:15:12 +0200166be forwarded to the list or be deleted without notification. An auto-responder
167bot is in place to try to detect e-mails from people asking for help and to
168redirect them to the mailing list. Do not be surprised if this happens to you.
Willy Tarreau11e334d92015-09-20 22:31:42 +0200169
170If you'd like a feature to be added but you think you don't have the skills to
171implement it yourself, you should follow these steps :
172
173 1. discuss the feature on the mailing list. It is possible that someone
174 else has already implemented it, or that someone will tell you how to
175 proceed without it, or even why not to do it. It is also possible that
176 in fact it's quite easy to implement and people will guide you through
177 the process. That way you'll finally have YOUR patch merged, providing
178 the feature YOU need.
179
180 2. if you really can't code it yourself after discussing it, then you may
181 consider contacting someone to do the job for you. Some people on the
182 list might sometimes be OK with trying to do it.
183
Willy Tarreau09e0d742019-06-15 17:15:12 +0200184The version control system used by the project (Git) keeps authorship
185information in the form of the patch author's e-mail address. This way you will
186be credited for your work in the project's history. If you contract with
187someone to implement your idea you may have to discuss such modalities with
188the person doing the work as by default this person will be mentioned as the
189work's author.
190
Willy Tarreau11e334d92015-09-20 22:31:42 +0200191
Tim Duesterhus2847f142019-06-15 19:47:29 +0200192Rules: the 12 laws of patch contribution
193----------------------------------------
Willy Tarreau11e334d92015-09-20 22:31:42 +0200194
195People contributing patches must apply the following rules. That may sound heavy
196at the beginning but it's common sense more than anything else and contributors
197do not think about them anymore after a few patches.
198
Willy Tarreau138544f2017-03-31 16:24:44 +02001991) Comply with the license
200
201 Before modifying some code, you have read the LICENSE file ("main license")
Willy Tarreau11e334d92015-09-20 22:31:42 +0200202 coming with the sources, and all the files this file references. Certain
203 files may be covered by different licenses, in which case it will be
204 indicated in the files themselves. In any case, you agree to respect these
205 licenses and to contribute your changes under the same licenses. If you want
206 to create new files, they will be under the main license, or any license of
207 your choice that you have verified to be compatible with the main license,
Tim Düsterhus4896c442016-11-29 02:15:19 +0100208 and that will be explicitly mentioned in the affected files. The project's
Willy Tarreau11e334d92015-09-20 22:31:42 +0200209 maintainers are free to reject contributions proposing license changes they
210 feel are not appropriate or could cause future trouble.
211
Willy Tarreau138544f2017-03-31 16:24:44 +02002122) Develop on development branch, not stable ones
213
214 Your work may only be based on the latest development version. No development
Willy Tarreau11e334d92015-09-20 22:31:42 +0200215 is made on a stable branch. If your work needs to be applied to a stable
216 branch, it will first be applied to the development branch and only then will
217 be backported to the stable branch. You are responsible for ensuring that
218 your work correctly applies to the development version. If at any moment you
219 are going to work on restructuring something important which may impact other
220 contributors, the rule that applies is that the first sent is the first
221 served. However it is considered good practice and politeness to warn others
222 in advance if you know you're going to make changes that may force them to
223 re-adapt their code, because they did probably not expect to have to spend
224 more time discovering your changes and rebasing their work.
225
Willy Tarreau138544f2017-03-31 16:24:44 +02002263) Read and respect the coding style
227
228 You have read and understood "doc/coding-style.txt", and you're actively
Willy Tarreau11e334d92015-09-20 22:31:42 +0200229 determined to respect it and to enforce it on your coworkers if you're going
230 to submit a team's work. We don't care what text editor you use, whether it's
231 an hex editor, cat, vi, emacs, Notepad, Word, or even Eclipse. The editor is
232 only the interface between you and the text file. What matters is what is in
233 the text file in the end. The editor is not an excuse for submitting poorly
234 indented code, which only proves that the person has no consideration for
235 quality and/or has done it in a hurry (probably worse). Please note that most
236 bugs were found in low-quality code. Reviewers know this and tend to be much
Ilya Shipitsin2a950d02020-03-06 13:07:38 +0500237 more reluctant to accept poorly formatted code because by experience they
Willy Tarreau11e334d92015-09-20 22:31:42 +0200238 won't trust their author's ability to write correct code. It is also worth
239 noting that poor quality code is painful to read and may result in nobody
240 willing to waste their time even reviewing your work.
241
Willy Tarreau138544f2017-03-31 16:24:44 +02002424) Present clean work
243
244 The time it takes for you to polish your code is always much smaller than the
Willy Tarreau11e334d92015-09-20 22:31:42 +0200245 time it takes others to do it for you, because they always have to wonder if
246 what they see is intended (meaning they didn't understand something) or if it
247 is a mistake that needs to be fixed. And since there are less reviewers than
248 submitters, it is vital to spread the effort closer to where the code is
249 written and not closer to where it gets merged. For example if you have to
250 write a report for a customer that your boss wants to review before you send
251 it to the customer, will you throw on his desk a pile of paper with stains,
252 typos and copy-pastes everywhere ? Will you say "come on, OK I made a mistake
253 in the company's name but they will find it by themselves, it's obvious it
254 comes from us" ? No. When in doubt, simply ask for help on the mailing list.
255
Willy Tarreau138544f2017-03-31 16:24:44 +02002565) Documentation is very important
257
258 There are four levels of importance of quality in the project :
Willy Tarreau11e334d92015-09-20 22:31:42 +0200259
260 - The most important one, and by far, is the quality of the user-facing
261 documentation. This is the first contact for most users and it immediately
262 gives them an accurate idea of how the project is maintained. Dirty docs
263 necessarily belong to a dirty project. Be careful to the way the text you
264 add is presented and indented. Be very careful about typos, usual mistakes
265 such as double consonants when only one is needed or "it's" instead of
Tim Duesterhus2847f142019-06-15 19:47:29 +0200266 "its", don't mix US English and UK English in the same paragraph, etc.
Willy Tarreau11e334d92015-09-20 22:31:42 +0200267 When in doubt, check in a dictionary. Fixes for existing typos in the doc
268 are always welcome and chasing them is a good way to become familiar with
269 the project and to get other participants' respect and consideration.
270
271 - The second most important level is user-facing messages emitted by the
272 code. You must try to see all the messages your code produces to ensure
273 they are understandable outside of the context where you wrote them,
274 because the user often doesn't expect them. That's true for warnings, and
275 that's even more important for errors which prevent the program from
276 working and which require an immediate and well understood fix in the
277 configuration. It's much better to say "line 35: compression level must be
278 an integer between 1 and 9" than "invalid argument at line 35". In HAProxy,
279 error handling roughly represents half of the code, and that's about 3/4 of
280 the configuration parser. Take the time to do something you're proud of. A
281 good rule of thumb is to keep in mind that your code talks to a human and
Jackie Tapia749f74c2020-07-22 18:59:40 -0500282 tries to teach them how to proceed. It must then speak like a human.
Willy Tarreau11e334d92015-09-20 22:31:42 +0200283
284 - The third most important level is the code and its accompanying comments,
285 including the commit message which is a complement to your code and
286 comments. It's important for all other contributors that the code is
287 readable, fluid, understandable and that the commit message describes what
288 was done, the choices made, the possible alternatives you thought about,
289 the reason for picking this one and its limits if any. Comments should be
290 written where it's easy to have a doubt or after some error cases have been
291 wiped out and you want to explain what possibilities remain. All functions
292 must have a comment indicating what they take on input and what they
293 provide on output. Please adjust the comments when you copy-paste a
294 function or change its prototype, this type of lazy mistake is too common
295 and very confusing when reading code later to debug an issue. Do not forget
296 that others will feel really angry at you when they have to dig into your
297 code for a bug that your code caused and they feel like this code is dirty
298 or confusing, that the commit message doesn't explain anything useful and
299 that the patch should never have been accepted in the first place. That
300 will strongly impact your reputation and will definitely affect your
301 chances to contribute again!
302
303 - The fourth level of importance is in the technical documentation that you
304 may want to add with your code. Technical documentation is always welcome
305 as it helps others make the best use of your work and to go exactly in the
306 direction you thought about during the design. This is also what reduces
307 the risk that your design gets changed in the near future due to a misuse
308 and/or a poor understanding. All such documentation is actually considered
309 as a bonus. It is more important that this documentation exists than that
310 it looks clean. Sometimes just copy-pasting your draft notes in a file to
311 keep a record of design ideas is better than losing them. Please do your
312 best so that other ones can read your doc. If these docs require a special
313 tool such as a graphics utility, ensure that the file name makes it
314 unambiguous how to process it. So there are no rules here for the contents,
315 except one. Please write the date in your file. Design docs tend to stay
316 forever and to remain long after they become obsolete. At this point that
317 can cause harm more than it can help. Writing the date in the document
318 helps developers guess the degree of validity and/or compare them with the
319 date of certain commits touching the same area.
320
Willy Tarreau138544f2017-03-31 16:24:44 +02003216) US-ASCII only!
322
323 All text files and commit messages are written using the US-ASCII charset.
Willy Tarreau11e334d92015-09-20 22:31:42 +0200324 Please be careful that your contributions do not contain any character not
325 printable using this charset, as they will render differently in different
326 editors and/or terminals. Avoid latin1 and more importantly UTF-8 which some
327 editors tend to abuse to replace some US-ASCII characters with their
328 typographic equivalent which aren't readable anymore in other editors. The
329 only place where alternative charsets are tolerated is in your name in the
330 commit message, but it's at your own risk as it can be mangled during the
331 merge. Anyway if you have an e-mail address, you probably have a valid
332 US-ASCII representation for it as well.
333
Willy Tarreau138544f2017-03-31 16:24:44 +02003347) Comments
335
336 Be careful about comments when you move code around. It's not acceptable that
Willy Tarreau11e334d92015-09-20 22:31:42 +0200337 a block of code is moved to another place leaving irrelevant comments at the
338 old place, just like it's not acceptable that a function is duplicated without
339 the comments being adjusted. The example below started to become quite common
340 during the 1.6 cycle, it is not acceptable and wastes everyone's time :
341
342 /* Parse switching <str> to build rule <rule>. Returns 0 on error. */
343 int parse_switching_rule(const char *str, struct rule *rule)
344 {
345 ...
346 }
347
348 /* Parse switching <str> to build rule <rule>. Returns 0 on error. */
349 void execute_switching_rule(struct rule *rule)
350 {
351 ...
352 }
353
354 This patch is not acceptable either (and it's unfortunately not that rare) :
355
356 + if (!session || !arg || list_is_empty(&session->rules->head))
357 + return 0;
358 +
359 /* Check if session->rules is valid before dereferencing it */
360 if (!session->rules_allocated)
361 return 0;
362
363 - if (!arg || list_is_empty(&session->rules->head))
364 - return 0;
365 -
366
Willy Tarreau138544f2017-03-31 16:24:44 +02003678) Short, readable identifiers
368
369 Limit the length of your identifiers in the code. When your identifiers start
Willy Tarreau11e334d92015-09-20 22:31:42 +0200370 to sound like sentences, it's very hard for the reader to keep on track with
371 what operation they are observing. Also long names force expressions to fit
372 on several lines which also cause some difficulties to the reader. See the
373 example below :
374
375 int file_name_len_including_global_path;
376 int file_name_len_without_global_path;
377 int global_path_len_or_zero_if_default;
378
379 if (global_path)
380 global_path_len_or_zero_if_default = strlen(global_path);
381 else
382 global_path_len_or_zero_if_default = 0;
383
384 file_name_len_without_global_path = strlen(file_name);
385 file_name_len_including_global_path =
386 file_name_len_without_global_path + 1 + /* for '/' */
387 global_path_len_or_zero_if_default ?
388 global_path_len_or_zero_if_default : default_path_len;
389
390 Compare it to this one :
391
392 int f, p;
393
394 p = global_path ? strlen(global_path) : default_path_len;
395 f = p + 1 + strlen(file_name); /* 1 for '/' */
396
397 A good rule of thumb is that if your identifiers start to contain more than
398 3 words or more than 15 characters, they can become confusing. For function
399 names it's less important especially if these functions are rarely used or
Bertrand Jacquind5e4de82018-10-13 16:06:18 +0100400 are used in a complex context where it is important to differentiate between
Willy Tarreau11e334d92015-09-20 22:31:42 +0200401 their multiple variants.
402
Willy Tarreau138544f2017-03-31 16:24:44 +02004039) Unified diff only
404
405 The best way to build your patches is to use "git format-patch". This means
406 that you have committed your patch to a local branch, with an appropriate
407 subject line and a useful commit message explaining what the patch attempts
408 to do. It is not strictly required to use git, but what is strictly required
Bertrand Jacquind5e4de82018-10-13 16:06:18 +0100409 is to have all these elements in the same mail, easily distinguishable, and
Willy Tarreau138544f2017-03-31 16:24:44 +0200410 a patch in "diff -up" format (which is also the format used by Git). This
411 means the "unified" diff format must be used exclusively, and with the
412 function name printed in the diff header of each block. That significantly
413 helps during reviews. Keep in mind that most reviews are done on the patch
414 and not on the code after applying the patch. Your diff must keep some
415 context (3 lines above and 3 lines below) so that there's no doubt where the
416 code has to be applied. Don't change code outside of the context of your
417 patch (eg: take care of not adding/removing empty lines once you remove
Willy Tarreau11e334d92015-09-20 22:31:42 +0200418 your debugging code). If you are using Git (which is strongly recommended),
Willy Tarreau11e334d92015-09-20 22:31:42 +0200419 always use "git show" after doing a commit to ensure it looks good, and
420 enable syntax coloring that will automatically report in red the trailing
421 spaces or tabs that your patch added to the code and that must absolutely be
422 removed. These ones cause a real pain to apply patches later because they
423 mangle the context in an invisible way. Such patches with trailing spaces at
424 end of lines will be rejected.
425
Willy Tarreau138544f2017-03-31 16:24:44 +020042610) One patch per feature
427
428 Please cut your work in series of patches that can be independently reviewed
429 and merged. Each patch must do something on its own that you can explain to
430 someone without being ashamed of what you did. For example, you must not say
431 "This is the patch that implements SSL, it was tricky". There's clearly
432 something wrong there, your patch will be huge, will definitely break things
433 and nobody will be able to figure what exactly introduced the bug. However
434 it's much better to say "I needed to add some fields in the session to store
435 the SSL context so this patch does this and doesn't touch anything else, so
436 it's safe". Also when dealing with series, you will sometimes fix a bug that
437 one of your patches introduced. Please do merge these fixes (eg: using git
438 rebase -i and squash or fixup), as it is not acceptable to see patches which
439 introduce known bugs even if they're fixed later. Another benefit of cleanly
440 splitting patches is that if some of your patches need to be reworked after
441 a review, the other ones can still be merged so that you don't need to care
442 about them anymore. When sending multiple patches for review, prefer to send
443 one e-mail per patch than all patches in a single e-mail. The reason is that
444 not everyone is skilled in all areas nor has the time to review everything
445 at once. With one patch per e-mail, it's easy to comment on a single patch
446 without giving an opinion on the other ones, especially if a long thread
447 starts about one specific patch on the mailing list. "git send-email" does
448 that for you though it requires a few trials before getting it right.
449
450 If you can, please always put all the bug fixes at the beginning of the
451 series. This often makes it easier to backport them because they will not
Willy Tarreau09e0d742019-06-15 17:15:12 +0200452 depend on context that your other patches changed. As a hint, if you can't
453 do this, there are little chances that your bug fix can be backported.
Willy Tarreau11e334d92015-09-20 22:31:42 +0200454
Willy Tarreau138544f2017-03-31 16:24:44 +020045511) Real commit messages please!
Willy Tarreau11e334d92015-09-20 22:31:42 +0200456
Willy Tarreau41f638c2019-07-26 15:21:54 +0200457 The commit message is how you're trying to convince a maintainer to adopt
458 your work and maintain it as long as possible. A dirty commit message almost
459 always comes with dirty code. Too short a commit message indicates that too
460 short an analysis was done and that side effects are extremely likely to be
461 encountered. It's the maintainer's job to decide to accept this work in its
462 current form or not, with the known constraints. Some patches which rework
463 architectural parts or fix sensitive bugs come with 20-30 lines of design
464 explanations, limitations, hypothesis or even doubts, and despite this it
465 happens when reading them 6 months later while trying to identify a bug that
466 developers still miss some information about corner cases.
467
468 So please properly format your commit messages. To get an idea, just run
Willy Tarreau138544f2017-03-31 16:24:44 +0200469 "git log" on the file you've just modified. Patches always have the format
470 of an e-mail made of a subject, a description and the actual patch. If you
471 are sending a patch as an e-mail formatted this way, it can quickly be
472 applied with limited effort so that's acceptable :
Willy Tarreau11e334d92015-09-20 22:31:42 +0200473
Willy Tarreau138544f2017-03-31 16:24:44 +0200474 - A subject line (may wrap to the next line, but please read below)
475 - an empty line (subject delimiter)
476 - a non-empty description (the body of the e-mail)
477 - the patch itself
Willy Tarreau11e334d92015-09-20 22:31:42 +0200478
Willy Tarreau138544f2017-03-31 16:24:44 +0200479 The subject describes the "What" of the change ; the description explains
480 the "why", the "how" and sometimes "what next". For example a commit message
481 looking like this will be rejected :
Willy Tarreau11e334d92015-09-20 22:31:42 +0200482
Willy Tarreau138544f2017-03-31 16:24:44 +0200483 | From: Mr Foobar <foobar@example.com>
484 | Subject: BUG: fix typo in ssl_sock
485 |
486
487 This one as well (too long subject, not the right place for the details) :
488
489 | From: Mr Foobar <foobar@example.com>
490 | Subject: BUG/MEDIUM: ssl: use an error flag to prevent ssl_read() from
491 | returning 0 when dealing with large buffers because that can cause
492 | an infinite loop
493 |
494
495 This one ought to be used instead :
496
497 | From: Mr Foobar <foobar@example.com>
498 | Subject: BUG/MEDIUM: ssl: fix risk of infinite loop in ssl_sock
499 |
500 | ssl_read() must not return 0 on error or the caller may loop forever.
501 | Instead we add a flag to the connection to notify about the error and
502 | check it at all call places. This situation can only happen with large
503 | buffers so a workaround is to limit buffer sizes. Another option would
504 | have been to return -1 but it required to use signed ints everywhere
505 | and would have made the patch larger and riskier. This fix should be
506 | backported to versions 1.2 and upper.
507
508 It is important to understand that for any reader to guess the text above
509 when it's absent, it will take a huge amount of time. If you made the
510 analysis leading to your patch, you must explain it, including the ideas
511 you dropped if you had a good reason for this.
512
513 While it's not strictly required to use Git, it is strongly recommended
514 because it helps you do the cleanest job with the least effort. But if you
515 are comfortable with writing clean e-mails and inserting your patches, you
516 don't need to use Git.
517
518 But in any case, it is important that there is a clean description of what
519 the patch does, the motivation for what it does, why it's the best way to do
Willy Tarreau41f638c2019-07-26 15:21:54 +0200520 it, its impacts, and what it does not yet cover. And this is particularly
521 important for bugs. A patch tagged "BUG" must absolutely explain what the
522 problem is, why it is considered as a bug. Anybody, even non-developers,
523 should be able to tell whether or not a patch is likely to address an issue
524 they are facing. Indicating what the code will do after the fix doesn't help
525 if it does not say what problem is encountered without the patch. Note that
526 in some cases the bug is purely theorical and observed by reading the code.
527 In this case it's perfectly fine to provide an estimate about possible
528 effects. Also, in HAProxy, like many projects which take a great care of
529 maintaining stable branches, patches are reviewed later so that some of them
530 can be backported to stable releases.
Willy Tarreau138544f2017-03-31 16:24:44 +0200531
532 While reviewing hundreds of patches can seem cumbersome, with a proper
533 formatting of the subject line it actually becomes very easy. For example,
534 here's how one can find patches that need to be reviewed for backports (bugs
535 and doc) between since commit ID 827752e :
536
537 $ git log --oneline 827752e.. | grep 'BUG\|DOC'
538 0d79cf6 DOC: fix function name
539 bc96534 DOC: ssl: missing LF
Joseph Herlante07bc142018-11-09 17:44:10 -0800540 10ec214 BUG/MEDIUM: lua: the lua function Channel:close() causes a segf
Willy Tarreau138544f2017-03-31 16:24:44 +0200541 bdc97a8 BUG/MEDIUM: lua: outgoing connection was broken since 1.6-dev2
542 ba56d9c DOC: mention support for RFC 5077 TLS Ticket extension in start
543 f1650a8 DOC: clarify some points about SSL and the proxy protocol
544 b157d73 BUG/MAJOR: peers: fix current table pointer not re-initialized
545 e1ab808 BUG/MEDIUM: peers: fix wrong message id on stick table updates
546 cc79b00 BUG/MINOR: ssl: TLS Ticket Key rotation broken via socket comma
547 d8e42b6 DOC: add new file intro.txt
548 c7d7607 BUG/MEDIUM: lua: bad error processing
549 386a127 DOC: match several lua configuration option names to those impl
550 0f4eadd BUG/MEDIUM: counters: ensure that src_{inc,clr}_gpc0 creates a
551
552 It is made possible by the fact that subject lines are properly formatted and
553 always respect the same principle : one part indicating the nature and
554 severity of the patch, another one to indicate which subsystem is affected,
555 and the last one is a succinct description of the change, with the important
556 part at the beginning so that it's obvious what it does even when lines are
557 truncated like above. The whole stable maintenance process relies on this.
558 For this reason, it is mandatory to respect some easy rules regarding the
559 way the subject is built. Please see the section below for more information
560 regarding this formatting.
561
Willy Tarreau9d84cd62017-07-18 06:56:40 +0200562 As a rule of thumb, your patch MUST NEVER be made only of a subject line,
Willy Tarreau138544f2017-03-31 16:24:44 +0200563 it *must* contain a description. Even one or two lines, or indicating
564 whether a backport is desired or not. It turns out that single-line commits
565 are so rare in the Git world that they require special manual (hence
566 painful) handling when they are backported, and at least for this reason
567 it's important to keep this in mind.
568
Willy Tarreau09e0d742019-06-15 17:15:12 +0200569 Maintainers who pick your patch may slightly adjust the description as they
570 see fit. Do not see this as a failure to do a clean job, it just means they
571 think it will help them do their daily job this way. The code may also be
572 slightly adjusted before being merged (non-functional changes only, fix for
573 typos, tabs vs spaces for example), unless your patch contains a
574 Signed-off-By tag, in which case they will either modify it and mention the
575 changes after your Signed-off-By line, or (more likely) ask you to perform
576 these changes yourself. This ability to slightly adjust a patch before
577 merging is is the main reason for not using pull requests which do not
578 provide this facility and will require to iterate back and forth with the
579 submitter and significantly delay the patch inclusion.
580
Willy Tarreau9d84cd62017-07-18 06:56:40 +0200581 Each patch fixing a bug MUST be tagged with "BUG", a severity level, an
582 indication of the affected subsystem and a brief description of the nature
583 of the issue in the subject line, and a detailed analysis in the message
584 body. The explanation of the user-visible impact and the need for
585 backporting to stable branches or not are MANDATORY. Bug fixes with no
586 indication will simply be rejected as they are very likely to cause more
587 harm when nobody is able to tell whether or not the patch needs to be
588 backported or can be reverted in case of regression.
589
Frédéric Lécaille4891e402018-06-19 14:06:07 +0200590 When fixing a bug which is reproducible, if possible, the contributors are
591 strongly encouraged to write a regression testing VTC file for varnishtest
592 to add to reg-tests directory. More information about varnishtest may be
593 found in README file of reg-tests directory and in doc/regression-testing.txt
594 file.
595
Willy Tarreau138544f2017-03-31 16:24:44 +020059612) Discuss on the mailing list
597
Willy Tarreau09e0d742019-06-15 17:15:12 +0200598 Note, some first-time contributors might feel impressed or scared by posting
599 to a list. This list is frequented only by nice people who are willing to
600 help you polish your work so that it is perfect and can last long. What you
601 think could be perceived as a proof of incompetence or lack of care will
602 instead be a proof of your ability to work with a community. You will not be
603 judged nor blamed for making mistakes. The project maintainers are the ones
604 creating the most bugs and mistakes anyway, and nobody knows the project in
605 its entirety anymore so you're just like anyone else. And people who have no
606 consideration for other's work are quickly ejected from the list so the
607 place is as safe and welcoming to new contributors as it is to long time
608 ones.
609
Willy Tarreau138544f2017-03-31 16:24:44 +0200610 When submitting changes, please always CC the mailing list address so that
611 everyone gets a chance to spot any issue in your code. It will also serve
612 as an advertisement for your work, you'll get more testers quicker and
613 you'll feel better knowing that people really use your work. It's often
614 convenient to prepend "[PATCH]" in front of your mail's subject to mention
615 that this e-mail contains a patch (or a series of patches), because it will
616 easily catch reviewer's attention. It's automatically done by tools such as
617 "git format-patch" and "git send-email". If you don't want your patch to be
618 merged yet and prefer to show it for discussion, better tag it as "[RFC]"
619 (stands for "Request For Comments") and it will be reviewed but not merged
620 without your approval. It is also important to CC any author mentioned in
621 the file you change, or a subsystem maintainers whose address is mentioned
622 in a MAINTAINERS file. Not everyone reads the list on a daily basis so it's
623 very easy to miss some changes. Don't consider it as a failure when a
624 reviewer tells you you have to modify your patch, actually it's a success
625 because now you know what is missing for your work to get accepted. That's
626 why you should not hesitate to CC enough people. Don't copy people who have
627 no deal with your work area just because you found their address on the
628 list. That's the best way to appear careless about their time and make them
629 reject your changes in the future.
630
Willy Tarreau11e334d92015-09-20 22:31:42 +0200631
632Patch classifying rules
633-----------------------
634
635There are 3 criteria of particular importance in any patch :
636 - its nature (is it a fix for a bug, a new feature, an optimization, ...)
637 - its importance, which generally reflects the risk of merging/not merging it
638 - what area it applies to (eg: http, stats, startup, config, doc, ...)
639
640It's important to make these 3 criteria easy to spot in the patch's subject,
641because it's the first (and sometimes the only) thing which is read when
642reviewing patches to find which ones need to be backported to older versions.
643It also helps when trying to find which patch is the most likely to have caused
644a regression.
645
646Specifically, bugs must be clearly easy to spot so that they're never missed.
647Any patch fixing a bug must have the "BUG" tag in its subject. Most common
648patch types include :
649
650 - BUG fix for a bug. The severity of the bug should also be indicated
651 when known. Similarly, if a backport is needed to older versions,
Willy Tarreau41f638c2019-07-26 15:21:54 +0200652 it should be indicated on the last line of the commit message. The
653 commit message MUST ABSOLUTELY describe the problem and its impact
654 to non-developers. Any user must be able to guess if this patch is
655 likely to fix a problem they are facing. Even if the bug was
656 discovered by accident while reading the code or running an
657 automated tool, it is mandatory to try to estimate what potential
658 issue it might cause and under what circumstances. There may even
659 be security implications sometimes so a minimum analysis is really
660 required. Also please think about stable maintainers who have to
661 build the release notes, they need to have enough input about the
662 bug's impact to explain it. If the bug has been identified as a
663 regression brought by a specific patch or version, this indication
664 will be appreciated too. New maintenance releases are generally
665 emitted when a few of these patches are merged. If the bug is a
666 vulnerability for which a CVE identifier was assigned before you
667 publish the fix, you can mention it in the commit message, it will
668 help distro maintainers.
Willy Tarreau11e334d92015-09-20 22:31:42 +0200669
Tim Düsterhus4896c442016-11-29 02:15:19 +0100670 - CLEANUP code cleanup, silence of warnings, etc... theoretically no impact.
Willy Tarreau11e334d92015-09-20 22:31:42 +0200671 These patches will rarely be seen in stable branches, though they
672 may appear when they remove some annoyance or when they make
673 backporting easier. By nature, a cleanup is always of minor
674 importance and it's not needed to mention it.
675
676 - DOC updates to any of the documentation files, including README. Many
677 documentation updates are backported since they don't impact the
678 product's stability and may help users avoid bugs. So please
679 indicate in the commit message if a backport is desired. When a
680 feature gets documented, it's preferred that the doc patch appears
681 in the same patch or after the feature patch, but not before, as it
682 becomes confusing when someone working on a code base including
683 only the doc patch won't understand why a documented feature does
684 not work as documented.
685
686 - REORG code reorganization. Some blocks may be moved to other places,
687 some important checks might be swapped, etc... These changes
688 always present a risk of regression. For this reason, they should
689 never be mixed with any bug fix nor functional change. Code is
690 only moved as-is. Indicating the risk of breakage is highly
691 recommended. Minor breakage is tolerated in such patches if trying
692 to fix it at once makes the whole change even more confusing. That
693 may happen for example when some #ifdefs need to be propagated in
694 every file consecutive to the change.
695
696 - BUILD updates or fixes for build issues. Changes to makefiles also fall
697 into this category. The risk of breakage should be indicated if
698 known. It is also appreciated to indicate what platforms and/or
699 configurations were tested after the change.
700
701 - OPTIM some code was optimised. Sometimes if the regression risk is very
702 low and the gains significant, such patches may be merged in the
703 stable branch. Depending on the amount of code changed or replaced
704 and the level of trust the author has in the change, the risk of
Willy Tarreau09e0d742019-06-15 17:15:12 +0200705 regression should be indicated. If the optimization depends on the
706 architecture or on build options, it is important to verify that
707 the code continues to work without it.
Willy Tarreau11e334d92015-09-20 22:31:42 +0200708
709 - RELEASE release of a new version (development or stable).
710
711 - LICENSE licensing updates (may impact distro packagers).
712
Frédéric Lécaillea8cf95d2018-06-20 10:14:01 +0200713 - REGTEST updates to any of the regression testing files found in reg-tests
714 directory, including README or any documentation file.
715
Willy Tarreau11e334d92015-09-20 22:31:42 +0200716
Willy Tarreau138544f2017-03-31 16:24:44 +0200717When the patch cannot be categorized, it's best not to put any type tag, and to
718only use a risk or complexity information only as below. This is commonly the
719case for new features, which development versions are mostly made of.
Willy Tarreau11e334d92015-09-20 22:31:42 +0200720
Willy Tarreau138544f2017-03-31 16:24:44 +0200721The importance, complexity of the patch, or severity of the bug it fixes must
Willy Tarreau11e334d92015-09-20 22:31:42 +0200722be indicated when relevant. A single upper-case word is preferred, among :
723
724 - MINOR minor change, very low risk of impact. It is often the case for
725 code additions that don't touch live code. As a rule of thumb, a
726 patch tagged "MINOR" is safe enough to be backported to stable
727 branches. For a bug, it generally indicates an annoyance, nothing
728 more.
729
730 - MEDIUM medium risk, may cause unexpected regressions of low importance or
731 which may quickly be discovered. In short, the patch is safe but
732 touches working areas and it is always possible that you missed
733 something you didn't know existed (eg: adding a "case" entry or
734 an error message after adding an error code to an enum). For a bug,
735 it generally indicates something odd which requires changing the
736 configuration in an undesired way to work around the issue.
737
738 - MAJOR major risk of hidden regression. This happens when large parts of
739 the code are rearranged, when new timeouts are introduced, when
740 sensitive parts of the session scheduling are touched, etc... We
741 should only exceptionally find such patches in stable branches when
742 there is no other option to fix a design issue. For a bug, it
743 indicates severe reliability issues for which workarounds are
744 identified with or without performance impacts.
745
746 - CRITICAL medium-term reliability or security is at risk and workarounds,
747 if they exist, might not always be acceptable. An upgrade is
748 absolutely required. A maintenance release may be emitted even if
749 only one of these bugs are fixed. Note that this tag is only used
750 with bugs. Such patches must indicate what is the first version
751 affected, and if known, the commit ID which introduced the issue.
752
753The expected length of the commit message grows with the importance of the
754change. While a MINOR patch may sometimes be described in 1 or 2 lines, MAJOR
755or CRITICAL patches cannot have less than 10-15 lines to describe exactly the
756impacts otherwise the submitter's work will be considered as rough sabotage.
Willy Tarreau09e0d742019-06-15 17:15:12 +0200757If you are sending a new patch series after a review, it is generally good to
758enumerate at the end of the commit description what changed from the previous
759one as it helps reviewers quickly glance over such changes and not re-read the
760rest.
Willy Tarreau11e334d92015-09-20 22:31:42 +0200761
762For BUILD, DOC and CLEANUP types, this tag is not always relevant and may be
763omitted.
764
765The area the patch applies to is quite important, because some areas are known
766to be similar in older versions, suggesting a backport might be desirable, and
767conversely, some areas are known to be specific to one version. The area is a
768single-word lowercase name the contributor find clear enough to describe what
Tim Duesterhus2847f142019-06-15 19:47:29 +0200769part is being touched. The following list of tags is suggested but not
770exhaustive:
Willy Tarreau11e334d92015-09-20 22:31:42 +0200771
772 - examples example files. Be careful, sometimes these files are packaged.
773
774 - tests regression test files. No code is affected, no need to upgrade.
775
Frédéric Lécaille4891e402018-06-19 14:06:07 +0200776 - reg-tests regression test files for varnishtest. No code is affected, no
777 need to upgrade.
778
Willy Tarreau11e334d92015-09-20 22:31:42 +0200779 - init initialization code, arguments parsing, etc...
780
781 - config configuration parser, mostly used when adding new config keywords
782
783 - http the HTTP engine
784
785 - stats the stats reporting engine
786
787 - cli the stats socket CLI
788
789 - checks the health checks engine (eg: when adding new checks)
790
791 - sample the sample fetch system (new fetch or converter functions)
792
793 - acl the ACL processing core or some ACLs from other areas
794
Willy Tarreau138544f2017-03-31 16:24:44 +0200795 - filters everything related to the filters core
796
Willy Tarreau11e334d92015-09-20 22:31:42 +0200797 - peers the peer synchronization engine
798
799 - lua the Lua scripting engine
800
801 - listeners everything related to incoming connection settings
802
803 - frontend everything related to incoming connection processing
804
805 - backend everything related to LB algorithms and server farm
806
807 - session session processing and flags (very sensible, be careful)
808
809 - server server connection management, queueing
810
Willy Tarreau138544f2017-03-31 16:24:44 +0200811 - spoe SPOE code
812
Willy Tarreau11e334d92015-09-20 22:31:42 +0200813 - ssl the SSL/TLS interface
814
815 - proxy proxy maintenance (start/stop)
816
817 - log log management
818
819 - poll any of the pollers
820
Willy Tarreau580727f2021-04-21 15:13:10 +0200821 - halog the halog sub-component in the admin directory
Willy Tarreau11e334d92015-09-20 22:31:42 +0200822
Willy Tarreau09e0d742019-06-15 17:15:12 +0200823 - htx general HTX subsystem
824
825 - mux-h1 HTTP/1.x multiplexer/demultiplexer
826
827 - mux-h2 HTTP/2 multiplexer/demultiplexer
828
829 - h1 general HTTP/1.x protocol parser
830
831 - h2 general HTTP/2 protocol parser
832
Willy Tarreau11e334d92015-09-20 22:31:42 +0200833Other names may be invented when more precise indications are meaningful, for
834instance : "cookie" which indicates cookie processing in the HTTP core. Last,
835indicating the name of the affected file is also a good way to quickly spot
836changes. Many commits were already tagged with "stream_sock" or "cfgparse" for
837instance.
838
839It is required that the type of change and the severity when relevant are
840indicated, as well as the touched area when relevant as well in the patch
841subject. Normally, we would have the 3 most often. The two first criteria should
842be present before a first colon (':'). If both are present, then they should be
843delimited with a slash ('/'). The 3rd criterion (area) should appear next, also
Willy Tarreau138544f2017-03-31 16:24:44 +0200844followed by a colon. Thus, all of the following subject lines are valid :
Willy Tarreau11e334d92015-09-20 22:31:42 +0200845
Willy Tarreau138544f2017-03-31 16:24:44 +0200846Examples of subject lines :
Willy Tarreau11e334d92015-09-20 22:31:42 +0200847 - DOC: document options forwardfor to logasap
848 - DOC/MAJOR: reorganize the whole document and change indenting
849 - BUG: stats: connection reset counters must be plain ascii, not HTML
850 - BUG/MINOR: stats: connection reset counters must be plain ascii, not HTML
851 - MEDIUM: checks: support multi-packet health check responses
852 - RELEASE: Released version 1.4.2
853 - BUILD: stats: stdint is not present on solaris
854 - OPTIM/MINOR: halog: make fgets parse more bytes by blocks
855 - REORG/MEDIUM: move syscall redefinition to specific places
856
857Please do not use square brackets anymore around the tags, because they induce
858more work when merging patches, which need to be hand-edited not to lose the
859enclosed part.
860
861In fact, one of the only square bracket tags that still makes sense is '[RFC]'
862at the beginning of the subject, when you're asking for someone to review your
863change before getting it merged. If the patch is OK to be merged, then it can
864be merge as-is and the '[RFC]' tag will automatically be removed. If you don't
865want it to be merged at all, you can simply state it in the message, or use an
866alternate 'WIP/' prefix in front of your tag tag ("work in progress").
867
868The tags are not rigid, follow your intuition first, and they may be readjusted
869when your patch is merged. It may happen that a same patch has a different tag
870in two distinct branches. The reason is that a bug in one branch may just be a
871cleanup or safety measure in the other one because the code cannot be triggered.
872
873
874Working with Git
875----------------
876
877For a more efficient interaction between the mainline code and your code, you
878are strongly encouraged to try the Git version control system :
879
880 http://git-scm.com/
881
882It's very fast, lightweight and lets you undo/redo your work as often as you
883want, without making your mistakes visible to the rest of the world. It will
884definitely help you contribute quality code and take other people's feedback
885in consideration. In order to clone the HAProxy Git repository :
886
887 $ git clone http://git.haproxy.org/git/haproxy.git/ (development)
888
889If you decide to use Git for your developments, then your commit messages will
890have the subject line in the format described above, then the whole description
891of your work (mainly why you did it) will be in the body. You can directly send
892your commits to the mailing list, the format is convenient to read and process.
893
894It is recommended to create a branch for your work that is based on the master
895branch :
896
897 $ git checkout -b 20150920-fix-stats master
898
899You can then do your work and even experiment with multiple alternatives if you
900are not completely sure that your solution is the best one :
901
902 $ git checkout -b 20150920-fix-stats-v2
903
904Then reorder/merge/edit your patches :
905
906 $ git rebase -i master
907
908When you think you're ready, reread your whole patchset to ensure there is no
Tim Düsterhus4896c442016-11-29 02:15:19 +0100909formatting or style issue :
Willy Tarreau11e334d92015-09-20 22:31:42 +0200910
911 $ git show master..
912
913And once you're satisfied, you should update your master branch to be sure that
Thiago Farina9f72a392016-04-01 16:43:50 -0300914nothing changed during your work (only needed if you left it unattended for days
Willy Tarreau11e334d92015-09-20 22:31:42 +0200915or weeks) :
916
917 $ git checkout -b 20150920-fix-stats-rebased
918 $ git fetch origin master:master
919 $ git rebase master
920
Thiago Farina9f72a392016-04-01 16:43:50 -0300921You can build a list of patches ready for submission like this :
Willy Tarreau11e334d92015-09-20 22:31:42 +0200922
923 $ git format-patch master
924
925The output files are the patches ready to be sent over e-mail, either via a
926regular e-mail or via git send-email (carefully check the man page). Don't
927destroy your other work branches until your patches get merged, it may happen
928that earlier designs will be preferred for various reasons. Patches should be
929sent to the mailing list : haproxy@formilux.org and CCed to relevant subsystem
930maintainers or authors of the modified files if their address appears at the
931top of the file.
932
Willy Tarreau09e0d742019-06-15 17:15:12 +0200933Please don't send pull requests, they are really inconvenient as they make it
934much more complicate to perform minor adjustments, and nobody benefits from
935any comment on the code while on a list all subscribers learn a little bit on
936each review of anyone else's code.
937
938
939What to do if your patch is ignored
940-----------------------------------
941
942All patches merged are acknowledged by the maintainer who picked it. If you
943didn't get an acknowledgement, check the mailing list archives to see if your
Tim Duesterhus2847f142019-06-15 19:47:29 +0200944mail was properly delivered there and possibly if anyone responded and you did
Willy Tarreau09e0d742019-06-15 17:15:12 +0200945not get their response (please look at http://haproxy.org/ for the mailing list
946archive's address).
947
Tim Duesterhus2847f142019-06-15 19:47:29 +0200948If you see that your mail is there but nobody responded, please recheck:
Willy Tarreau09e0d742019-06-15 17:15:12 +0200949 - was the subject clearly indicating that it was a patch and/or that you were
Tim Duesterhus2847f142019-06-15 19:47:29 +0200950 seeking some review?
Willy Tarreau09e0d742019-06-15 17:15:12 +0200951
Tim Duesterhus2847f142019-06-15 19:47:29 +0200952 - was your email mangled by your mail agent? If so it's possible that
Willy Tarreau09e0d742019-06-15 17:15:12 +0200953 nobody had the willingness yet to mention it.
954
Tim Duesterhus2847f142019-06-15 19:47:29 +0200955 - was your email sent as HTML? If so it definitely ended in spam boxes
956 regardless of the archives.
Willy Tarreau09e0d742019-06-15 17:15:12 +0200957
Tim Duesterhus2847f142019-06-15 19:47:29 +0200958 - did the patch violate some of the principles explained in this document?
Willy Tarreau09e0d742019-06-15 17:15:12 +0200959
960If none of these cases matches, it might simply be that everyone was busy when
961your patch was sent and that it was overlooked. In this case it's fine to
Tim Duesterhus2847f142019-06-15 19:47:29 +0200962either resubmit it or respond to your own email asking if anything's wrong
Willy Tarreau09e0d742019-06-15 17:15:12 +0200963about it. In general don't expect a response after one week of silence, just
Tim Duesterhus2847f142019-06-15 19:47:29 +0200964because your email will not appear in anyone else's current window. So after
Willy Tarreau09e0d742019-06-15 17:15:12 +0200965one week it's time to resubmit.
966
967Among the mistakes that tend to make reviewers not respond are those who send
968multiple versions of a patch in a row. It's natural for others then to wait for
969the series to stabilize. And once it doesn't move anymore everyone forgot about
Tim Duesterhus2847f142019-06-15 19:47:29 +0200970it. As a rule of thumb, if you have to update your original email more than
Willy Tarreau09e0d742019-06-15 17:15:12 +0200971twice, first double-check that your series is really ready for submission, and
972second, start a new thread and stop responding to the previous one. In this
973case it is well appreciated to mention a version of your patch set in the
974subject such as "[PATCH v2]", so that reviewers can immediately spot the new
975version and not waste their time on the old one.
976
977If you still do not receive any response, it is possible that you've already
978played your last card by not respecting the basic principles multiple times
979despite being told about it several times, and that nobody is willing to spend
980more of their time than normally needed with your work anymore. Your best
981option at this point probably is to ask "did I do something wrong" than to
982resend the same patches.
983
984
985How to be sure to irritate everyone
986-----------------------------------
987
988Among the best ways to quickly lose everyone's respect, there is this small
989selection, which should help you improve the way you work with others, if
Tim Duesterhus2847f142019-06-15 19:47:29 +0200990you notice you're already practising some of them:
Ilya Shipitsin2a950d02020-03-06 13:07:38 +0500991 - repeatedly send improperly formatted commit messages, with no type or
Willy Tarreau09e0d742019-06-15 17:15:12 +0200992 severity, or with no commit message body. These ones require manual
993 edition, maintainers will quickly learn to recognize your name.
994
995 - repeatedly send patches which break something, and disappear or take a long
996 time to provide a fix.
997
998 - fail to respond to questions related to features you have contributed in
999 the past, which can further lead to the feature being declared unmaintained
1000 and removed in a future version.
1001
1002 - send a new patch iteration without taking *all* comments from previous
Jackie Tapia749f74c2020-07-22 18:59:40 -05001003 review into consideration, so that the reviewer discovers they have to do
Willy Tarreau09e0d742019-06-15 17:15:12 +02001004 the exact same work again.
1005
1006 - "hijack" an existing thread to discuss something different or promote your
1007 work. This will generally make you look like a fool so that everyone wants
1008 to stay away from your e-mails.
1009
1010 - continue to send pull requests after having been explained why they are not
1011 welcome.
1012
1013 - give wrong advices to people asking for help, or sending them patches to
1014 try which make no sense, waste their time, and give them a bad impression
1015 of the people working on the project.
1016
1017 - be disrespectful to anyone asking for help or contributing some work. This
1018 may actually even get you kicked out of the list and banned from it.
Willy Tarreau11e334d92015-09-20 22:31:42 +02001019
1020-- end