DOC: add a CONTRIBUTING file
This file tries to explain in the most detailed way how to contribute
patches. A few parts of it were moved from the README. .gitignore was
updated.
diff --git a/README b/README
index f359550..cc3c94b 100644
--- a/README
+++ b/README
@@ -412,259 +412,7 @@
5) How to contribute
--------------------
-It is possible that you'll want to add a specific feature to satisfy your needs
-or one of your customers'. Contributions are welcome, however I'm often very
-picky about changes. I will generally reject patches that change massive parts
-of the code, or that touch the core parts without any good reason if those
-changes have not been discussed first.
-
-The proper place to discuss your changes is the HAProxy Mailing List. There are
-enough skilled readers to catch hazardous mistakes and to suggest improvements.
-I trust a number of them enough to merge a patch if they say it's OK, so using
-the list is the fastest way to get your code reviewed and merged. You can
-subscribe to it by sending an empty e-mail at the following address :
-
- haproxy+subscribe@formilux.org
-
-If you have an idea about something to implement, *please* discuss it on the
-list first. It has already happened several times that two persons did the same
-thing simultaneously. This is a waste of time for both of them. It's also very
-common to see some changes rejected because they're done in a way that will
-conflict with future evolutions, or that does not leave a good feeling. It's
-always unpleasant for the person who did the work, and it is unpleasant for me
-too because I value people's time and efforts. That would not happen if these
-were discussed first. There is no problem posting work in progress to the list,
-it happens quite often in fact. Also, don't waste your time with the doc when
-submitting patches for review, only add the doc with the patch you consider
-ready to merge.
-
-Another important point concerns code portability. Haproxy requires gcc as the
-C compiler, and may or may not work with other compilers. However it's known
-to build using gcc 2.95 or any later version. As such, it is important to keep
-in mind that certain facilities offered by recent versions must not be used in
-the code :
-
- - declarations mixed in the code (requires gcc >= 3.x)
- - GCC builtins without checking for their availability based on version and
- architecture ;
- - assembly code without any alternate portable form for other platforms
- - use of stdbool.h, "bool", "false", "true" : simply use "int", "0", "1"
- - in general, anything which requires C99 (such as declaring variables in
- "for" statements)
-
-Since most of these restrictions are just a matter of coding style, it is
-normally not a problem to comply.
-
-If your work is very confidential and you can't publicly discuss it, you can
-also mail me directly about it, but your mail may be waiting several days in
-the queue before you get a response.
-
-If you'd like a feature to be added but you think you don't have the skills to
-implement it yourself, you should follow these steps :
-
- 1. discuss the feature on the mailing list. It is possible that someone
- else has already implemented it, or that someone will tell you how to
- proceed without it, or even why not to do it. It is also possible that
- in fact it's quite easy to implement and people will guide you through
- the process. That way you'll finally have YOUR patch merged, providing
- the feature YOU need.
-
- 2. if you really can't code it yourself after discussing it, then you may
- consider contacting someone to do the job for you. Some people on the
- list might sometimes be OK with trying to do it.
-
-Note to contributors: it's very handy when patches comes with a properly
-formated subject. There are 3 criteria of particular importance in any patch :
-
- - its nature (is it a fix for a bug, a new feature, an optimization, ...)
- - its importance, which generally reflects the risk of merging/not merging it
- - what area it applies to (eg: http, stats, startup, config, doc, ...)
-
-It's important to make these 3 criteria easy to spot in the patch's subject,
-because it's the first (and sometimes the only) thing which is read when
-reviewing patches to find which ones need to be backported to older versions.
-
-Specifically, bugs must be clearly easy to spot so that they're never missed.
-Any patch fixing a bug must have the "BUG" tag in its subject. Most common
-patch types include :
-
- - BUG fix for a bug. The severity of the bug should also be indicated
- when known. Similarly, if a backport is needed to older versions,
- it should be indicated on the last line of the commit message. If
- the bug has been identified as a regression brought by a specific
- patch or version, this indication will be appreciated too. New
- maintenance releases are generally emitted when a few of these
- patches are merged.
-
- - CLEANUP code cleanup, silence of warnings, etc... theorically no impact.
- These patches will rarely be seen in stable branches, though they
- may appear when they remove some annoyance or when they make
- backporting easier. By nature, a cleanup is always minor.
-
- - REORG code reorganization. Some blocks may be moved to other places,
- some important checks might be swapped, etc... These changes
- always present a risk of regression. For this reason, they should
- never be mixed with any bug fix nor functional change. Code is
- only moved as-is. Indicating the risk of breakage is highly
- recommended.
-
- - BUILD updates or fixes for build issues. Changes to makefiles also fall
- into this category. The risk of breakage should be indicated if
- known. It is also appreciated to indicate what platforms and/or
- configurations were tested after the change.
-
- - OPTIM some code was optimised. Sometimes if the regression risk is very
- low and the gains significant, such patches may be merged in the
- stable branch. Depending on the amount of code changed or replaced
- and the level of trust the author has in the change, the risk of
- regression should be indicated.
-
- - RELEASE release of a new version (development or stable).
-
- - LICENSE licensing updates (may impact distro packagers).
-
-
-When the patch cannot be categorized, it's best not to put any tag. This is
-commonly the case for new features, which development versions are mostly made
-of.
-
-Additionally, the importance of the patch should be indicated when known. A
-single upper-case word is preferred, among :
-
- - MINOR minor change, very low risk of impact. It is often the case for
- code additions that don't touch live code. For a bug, it generally
- indicates an annoyance, nothing more.
-
- - MEDIUM medium risk, may cause unexpected regressions of low importance or
- which may quickly be discovered. For a bug, it generally indicates
- something odd which requires changing the configuration in an
- undesired way to work around the issue.
-
- - MAJOR major risk of hidden regression. This happens when I rearrange
- large parts of code, when I play with timeouts, with variable
- initializations, etc... We should only exceptionally find such
- patches in stable branches. For a bug, it indicates severe
- reliability issues for which workarounds are identified with or
- without performance impacts.
-
- - CRITICAL medium-term reliability or security is at risk and workarounds,
- if they exist, might not always be acceptable. An upgrade is
- absolutely required. A maintenance release may be emitted even if
- only one of these bugs are fixed. Note that this tag is only used
- with bugs. Such patches must indicate what is the first version
- affected, and if known, the commit ID which introduced the issue.
-
-If this criterion doesn't apply, it's best not to put it. For instance, most
-doc updates and most examples or test files are just added or updated without
-any need to qualify a level of importance.
-
-The area the patch applies to is quite important, because some areas are known
-to be similar in older versions, suggesting a backport might be desirable, and
-conversely, some areas are known to be specific to one version. When the tag is
-used alone, uppercase is preferred for readability, otherwise lowercase is fine
-too. The following tags are suggested but not limitative :
-
- - doc documentation updates or fixes. No code is affected, no need to
- upgrade. These patches can also be sent right after a new feature,
- to document it.
-
- - examples example files. Be careful, sometimes these files are packaged.
-
- - tests regression test files. No code is affected, no need to upgrade.
-
- - init initialization code, arguments parsing, etc...
-
- - config configuration parser, mostly used when adding new config keywords
-
- - http the HTTP engine
-
- - stats the stats reporting engine as well as the stats socket CLI
-
- - checks the health checks engine (eg: when adding new checks)
-
- - acl the ACL processing core or some ACLs from other areas
-
- - peers the peer synchronization engine
-
- - listeners everything related to incoming connection settings
-
- - frontend everything related to incoming connection processing
-
- - backend everything related to LB algorithms and server farm
-
- - session session processing and flags (very sensible, be careful)
-
- - server server connection management, queueing
-
- - proxy proxy maintenance (start/stop)
-
- - log log management
-
- - poll any of the pollers
-
- - halog the halog sub-component in the contrib directory
-
- - contrib any addition to the contrib directory
-
-Other names may be invented when more precise indications are meaningful, for
-instance : "cookie" which indicates cookie processing in the HTTP core. Last,
-indicating the name of the affected file is also a good way to quickly spot
-changes. Many commits were already tagged with "stream_sock" or "cfgparse" for
-instance.
-
-It is desired that AT LEAST one of the 3 criteria tags is reported in the patch
-subject. Ideally, we would have the 3 most often. The two first criteria should
-be present before a first colon (':'). If both are present, then they should be
-delimited with a slash ('/'). The 3rd criterion (area) should appear next, also
-followed by a colon. Thus, all of the following messages are valid :
-
-Examples of messages :
- - DOC: document options forwardfor to logasap
- - DOC/MAJOR: reorganize the whole document and change indenting
- - BUG: stats: connection reset counters must be plain ascii, not HTML
- - BUG/MINOR: stats: connection reset counters must be plain ascii, not HTML
- - MEDIUM: checks: support multi-packet health check responses
- - RELEASE: Released version 1.4.2
- - BUILD: stats: stdint is not present on solaris
- - OPTIM/MINOR: halog: make fgets parse more bytes by blocks
- - REORG/MEDIUM: move syscall redefinition to specific places
-
-Please do not use square brackets anymore around the tags, because they give me
-more work when merging patches. By default I'm asking Git to keep them but this
-causes trouble when patches are prefixed with the [PATCH] tag because in order
-not to store it, I have to hand-edit the patches. So as of now, I will ask Git
-to remove whatever is located between square brackets, which implies that any
-subject formatted the old way will have its tag stripped out.
-
-In fact, one of the only square bracket tags that still makes sense is '[RFC]'
-at the beginning of the subject, when you're asking for someone to review your
-change before getting it merged. If the patch is OK to be merged, then I can
-merge it as-is and the '[RFC]' tag will automatically be removed. If you don't
-want it to be merged at all, you can simply state it in the message, or use an
-alternate '[WIP]' tag ("work in progress").
-
-The tags are not rigid, follow your intuition first, anyway I reserve the right
-to change them when merging the patch. It may happen that a same patch has a
-different tag in two distinct branches. The reason is that a bug in one branch
-may just be a cleanup in the other one because the code cannot be triggered.
-
-
-For a more efficient interaction between the mainline code and your code, I can
-only strongly encourage you to try the Git version control system :
-
- http://git-scm.com/
-
-It's very fast, lightweight and lets you undo/redo your work as often as you
-want, without making your mistakes visible to the rest of the world. It will
-definitely help you contribute quality code and take other people's feedback
-in consideration. In order to clone the HAProxy Git repository :
-
- $ git clone http://git.haproxy.org/git/haproxy-1.5.git (stable 1.5)
- $ git clone http://git.haproxy.org/git/haproxy.git/ (development)
-
-If you decide to use Git for your developments, then your commit messages will
-have the subject line in the format described above, then the whole description
-of your work (mainly why you did it) will be in the body. You can directly send
-your commits to the mailing list, the format is convenient to read and process.
+Please carefully read the CONTRIBUTING file that comes with the sources. It is
+mandatory.
-- end