Updates on v4l/dvb README files

From: Mauro Carvalho Chehab <mchehab@infradead.org>

The previous README files were written when Mercurial tree usage
started. Since then, the procedures were being maturated, but the docs
were never updated to reflect the changes along the time.

This patch updates with the procedures and best practices currently in
use at LinuxTV.

Signed-off-by: Mauro Carvalho Chehab <mchehab@infradead.org>

3 files changed, 458 insertions, 244 deletions

diff --git a/README b/README
index c97db051e..396f5508e 100644
--- a/README
+++ b/README
@@ -1,10 +1,17 @@
 V4L and DVB documentation are at:
 	linux/Docummentation directory.
 
-to compile both v4l and dvb, just do:
+To compile both v4l and dvb, just do:
 	make
 
-to install over kernel's old files:
+To install over kernel's old files:
 	make install
 
-v4l dir is used as a temporary dir for building both v4l and dvb stuff.
+A more complete list of other possible usages for the building system
+can be found at:
+	INSTALL
+
+if you want to contribute by offering your work to V4L/DVB, please read:
+	README.patches
+
+Notice: v4l dir is used also as a temporary dir for building v4l/dvb modules.
diff --git a/README.HG b/README.HG
deleted file mode 100644
index e940aaf70..000000000
--- a/README.HG
+++ /dev/null
@@ -1,206 +0,0 @@
-Mauro Carvalho Chehab                                   2006 Mar 8
-
-This file describes the general procedures used by v4l-dvb developers
-who are responsible for maintaining V4L/DVB drivers. Some of these
-also applies to patch submitters.
-
-Current V4L/DVB tree uses a modern SCM system that fits better into 
-kernel development model, called Mercurial (aka hg).
-
-There are some tutorials, FAQs and other valuable informations at
-http://selenic.com/mercurial
-
-Mercurial is a distributed SCM, which means every developer gets his 
-own full copy of the repository (including the complete revision 
-history), and can work and commit locally without network connection. 
-The resulting changesets can then be exchanged between repositories and 
-finally published to the master repository in linuxtv.org. A list of
-current available repositories is available at: http://linuxtv.org/hg
-
-The master repository with stable patches is available at:
-http://linuxtv/org/hg/v4l-dvb
-
-Mercurial is organized with a master tag, called tip. This tag contains 
-the master repository that will be used by normal users and to generate 
-patches to kernel.
-
-This file postulates some simple rules for maintaing hg trees, as stated 
-below:
-
-1) It is strongly recommended that each developer be active at IRC 
-   channels (irc://irc.freenode.net) #v4l (for analog) and/or #linuxtv 
-   (for digital). It helps to have more discussions at major changes;
-
-2) Each developer may have one or more development trees, for his daily
-   work. It is recommended to have a tree called 'v4l-dvb' for each 
-   developer with their stable patches.
-
-3) After the patches are ready, developer should send an email to
-   v4l-dvb-maintainer list asking the maintainer to pull it from developer
-   repository, pushing it at master. The maintainer will analyse the patch
-   and publish at master hg if everything looks ok.
-
-4) Medium or major changes that needs modification on card coding, creating a 
-   new card type or requiring changes at core structs should be discussed first
-   at the Mailing Lists video4linux-list@redhat.com (analog/common parts)
-   and/or linux-dvb@linuxtv.org and at IRC to allow other contributors to
-   discuss about the way it will be included.
-
-5) Every developer should follow the "rules of thumb" of kernel development
-   stated at Linux source code, especially:
-
-	Documentation/SubmittingPatches
-	Documentation/SubmittingDrivers
-	Documentation/CodingStyle
-
-6) All commits should have a consistent message. On v4l-dvb, this is 
-   done by using:
-
-	make commit
-
-   This will run some scripts that will check changed files, generating 
-   a ChangeLog like comment (that will be removed from the commit) and 
-   prepare the last Signed-off-by field, as described below.
-
-7) Files can be added, removed or renamed at hg repository. This should 
-   be done by using:
-	hg add <files>
-	hg remove <files>
-	hg rename <source> <dest>
-	hg addremove [<files>]
-
-   *Warning* hg addremove will add/removes all files, including object 
-   files. Be careful! You can remove wrongly added files with hg remove.
-
-8) If the commit went wrong, hg allows you to undo the last commit, by 
-   using the command:
-
-	hg undo
-
-   This command will preserve the changes at the files. So, a new 
-   hg commit will redo the desired commit.
-
-9) To push the change to the repository you need to run:
-
-	hg push <url>
-
-10) To update from the master repository, it is needed to do:
-
-	make pull
-
-    After pulling from master, if there are some changes at local repository,
-    hg will require to merge it. This is done by
-	hg update -m
-	make commit
-
-11) For hg to work properly, these vars should be defined (replacing 
-    the names at the left):
-
-    HGUSER="Maintainer Name <maintainer-email@cvsmaintainersite.com>"
-
-    If you use a different login name at the repo, you may use:
-
-    CHANGE_LOG_LOGIN=my_log_name
-
-    You may also have it at ~/.hgrc, but, in this case, make commit will not
-    generate From: and Signed-off-by fields automatically.
-
-    Don't forget to export the vars, like:
-
-    export CHANGE_LOG_LOGIN HGUSER
-
-    It is strongly recommended to have these lines at .bashrc or .profile.
-
-12) All commit messages shall have a Developers Certificate of Origin
-    version 1.1 at commit log, as postulated at kernel's source at:
-
-	Documentation/SubmittingPatches
-
-    This is done by using Signed-off-by: fields at hg commit message.
-
-    It is not acceptable to use fake signatures like:
-
-	Signed-off-by: Fake me <me@snakeoilcompany.com>
-
-    The email should be a valid one.
-    The bottom signed-off-by should be the committer.
- 
-13) Commit messages are very relevant, since they will be used 
-    when generating the patches for v4l-dvb.git and to mainstream.
-
-    The format of commit message shall be:
-
-    patch subject
-    From: Patch Developer <patchdeveloper@patchdevelopersite.com>
-
-    patch descriptions
-
-    Signed-off-by: Patch Developer <patchdeveloper@patchdevelopersite.com>
-    Signed-off-by: Cvs Maintainer <cvsmaintainer@cvsmaintainersite.com>
-
-    All lines starting with # will be removed by make commit stripts.
-
-    Subject should be a brief description of the patch. Please 
-    notice that, with hg, there's no need (and not desired) to define a 
-    Subject: tag. The *first* msg line will be used as subject, just like 
-    git.
-    *WARNING* Be careful not to leave the first line blank, otherwise hg
-    will leave subject in blank.
-
-    From: line shouldn't be suppressed, since it will be used when 
-    converting to -git as patch author.
-
-    You may add other signers, if the patch were tested /co-developed 
-    by somebody else and he also wants to sign. The committer 
-    signed-off-by should be the last one.
-
-14) If the patch also affects other parts of kernel (like alsa 
-    or i2c), it is required that, at upstream submitting, the patch 
-    also goes to the maintainers of that subsystem. To do this, CVS 
-    maintainer shall add one or more cc: fields to the commit message, 
-    after the subject:
-
-    CC: someotherkerneldeveloper@someplace
-
-    Please notice that this is manually handled by the -git maintainer, 
-    so unnecessary usage should be avoided.
-
-15) Sometimes, mainstream changes do affect v4l-dvb tree, and requires 
-    to apply some kernel patches at the tree. This kind of commit should 
-    follow the rules above and should also have a line like:
-
-    kernel-sync
-
-    Patches with such lines will not be submitted upstream.
-
-16) sometimes it is necessary to introduce some testing code inside a 
-    module or remove parts that are not yet finished. Also, compatibility 
-    tests may be required to provide backporting.
-
-    To allow compatibility tests, "compat.h" should be included first. 
-    It does include also linux/version.h.
-
-    To include testing code, #if 0 or #if 1 may be used. If this code 
-    is meant to go also to kernel, this struct should be used:
-
-    #if 0 /* keep */
-	or
-    #if 1 /* keep */
-
-17) Nested #ifs are allowed, but the #elif macro shouldn't be used, 
-    since the macro preprocessing script used to prepare kernel upstream 
-    patches (v4l/scripts/gentree.pl) is not able to handle it.
-
-18) To import contributed stuff, a script is provided at tree and allows easy
-    import of a mbox-based patch emails. This is done with:
-	./mailimport <mbox file>
-    For it to work properly, git tools need to be installed at local machine,
-    since git have a gitimport script that is used by mailimport.
-    Also, hg have a feature, called mqueue, that allows having several patches
-    that can be applied/unapplied for testing. mailimport trusts on it to work,
-    so, this extension should be enabled for mailimport script to work.
-
-Good Work!
-Mauro
-
-Mauro Carvalho Chehab <mchehab .at. linuxtv .dot. org>
diff --git a/README.patches b/README.patches
index 5d045c1c5..9b81a75be 100644
--- a/README.patches
+++ b/README.patches
@@ -1,58 +1,471 @@
-Mauro Carvalho Chehab					2005 Dec 02
+Mauro Carvalho Chehab  <mchehab at infradead dot org>
+2007 Jun 22
 
-	The master copy of the video4linux and dvb kernel subsystem is now 
-maintained jointly at http://linuxtv.org/
+This file describes the general procedures used by the LinuxTV team (*)
+and by the v4l-dvb community.
 
-=== v4l-dvb snapshots available at linuxtv.org
+(*) This is just an aka for the main developers involved in V4L/DVB
+drivers. They are a volunteer and unremunerated group of people that
+have the common interest of providing a good support on Linux for
+receiving and capturing video streams from Web cams, Analog TV, Digital
+TV and radio broadcast AM/FM.
 
-	We are now publishing periodic snapshots (about once a month or 
-before rellevant changes) at linuxtv.org. The main idea is to have 
-"stable" snapshots on Linuxtv. You can check it at:
+   CONTENTS
+   ========
 
-http://linuxtv.org/downloads/snapshots
+	1. A Brief introduction about patch management
+	2. Git trees' relationships with v4l/dvb development
+	3. Mercurial trees used for v4l/dvb development
+	4. Community best practices
+	5. Knowing about newer patches committed at master hg repository
+	6. Patch handling for kernel submission
+	7. Patch submission from the community
+	8. Identifying regressions with Mercurial
 
-=== v4l-dvb quilt available at linuxtv.org
+1. A Brief introduction about patch management
+   ==========================================
 
-	It is also available patches against latest development kernel at: 
-http://linuxtv.org/downloads/quilt
+Current V4L/DVB development is based on a modern SCM system that
+fits better into kernel development model, called Mercurial (aka hg).
 
-	patches/series shows the correct order to apply.
+Kernel development model is based on a similar SCM, called git. While
+very powerful for distributed development, git usage is not simple for
+final users. That's the reason why hg was selected for V4L/DVB
+development.
 
-== Getting the latest Snapshot
+There are some tutorials, FAQs and other valuable information at
+http://selenic.com/mercurial about hg usage.
 
-	You must have mercurial installed in order to access the 
-repository. To get the latest sources from Hg you need to issue the 
-following command:
+Mercurial is a distributed SCM, which means every developer gets his
+own full copy of the repository (including the complete revision
+history), and can work and commit locally without network connection.
+The resulting changesets can then be exchanged between repositories and
+finally merged into a common repository on linuxtv.org.
 
-hg clone http://linuxtv.org/hg/v4l-dvb
+A list of current available repositories is available at:
+	http://linuxtv.org/hg
 
-* Patches should be built against v4l-dvb master Hg repository.
+2. Git trees' relationships with v4l/dvb development
+   =================================================
 
-=== How to get your changes into the mainline tree?
+The main kernel trees are hosted at http://git.kernel.org. Each tree
+is owned by a maintainer.
 
-1. Post your patches to the corresponding mailing list for review and 
-testing by other people. For analog or core changes, the mailing list is
-video4linux-list@redhat.com. For DVB changes, the mailing list
-is linux-dvb@linuxtv.org. The latest requires subscription.
-http://linuxtv.org/lists.php
+The main kernel trees is owned by Linus Torvalds, being located at:
+	http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git
 
-2.  Using [PATCH] at subject will help maintainers to better handle it.
+The subsystem master tree is owned by the subsystem maintainer (Mauro
+Carvalho Chehab) being located at:
+	http://git.kernel.org/?p=linux/kernel/git/mchehab/v4l-dvb.git
 
-3.  Please include a ChangeLog description in the headers of your patch.
+Before committing into the master -git tree, the finished patches from
+each maintainers tree are added on a staging tree, owned by the
+subsystem maintainer, at:
+	http://linuxtv.org/hg/v4l-dvb
 
-4.  Every patch shall have a Developers Certificate of Origin like
+The main function of this tree is to merge patches from other
+repositories and to test the entire subsystem with the finished patches.
 
-Signed-off-by: Your name <name@yoursite.com>
+Users are welcome to use, test and report any issues via the mailing
+lists or via the Kernel's bugzilla, available at:
+	http://bugzilla.kernel.org
 
-with name of people envolving on making it.
+Michael Krufky maintains a backport tree, containing a subset of the
+patches from the subsystem tree that are meant to be sent to kernel
+-stable team, at:
+	http://git.kernel.org/http://git.kernel.org/?p=linux/kernel/git/mkrufky/v4l-dvb-2.6.x.y.git
 
-	This should be a real name and address. The exact meaning of the 
-signed-off-by is postulated at linux source code, at file:
+3. Mercurial trees used for v4l/dvb development
+   ============================================
+
+V4L/DVB driver development is hosted at http://linuxtv.org. There are a
+number of trees there each owned by a developer of the LinuxTV team.
+
+When a developer believes that he has patches done to be merged, he
+sends a request the developers' mailing list and to the subsystem
+maintainer. The patches are analyzed and, if they look ok, merged into
+the master repository.
+
+It is good practice that each developer will have at least one tree
+called 'v4l-dvb', which keeps their patches, and periodically update
+this tree with the master tree's patches.
+
+4. Community best practices
+   ========================
+
+From accumulated experience, there are some basic rules that should
+be followed by the community:
+
+a) Every developer should follow the "rules of thumb" of kernel development
+   stated at Linux source code, especially those stated at kernel,
+   under:
+	Documentation/HOWTO
 	Documentation/SubmittingPatches
+	Documentation/SubmittingDrivers
+	Documentation/SubmitChecklist
+	Documentation/CodingStyle
+
+b) All commits at mercurial trees should have a consistent message,
+   describing the patch. This is done by using:
+
+	make commit
+
+   This will run some scripts that check changed files, correct
+   bad whitespace and prepare the last Signed-off-by: field, as
+   described below. A good comment will have a brief
+   description at the first line, up to 68 characters wide, a blank
+   line, the patch author's name on the third line, a blank line, and
+   then a brief description, with no more than 80 chars per line, e. g.:
+
+	   This patch does nothing
+
+	   From: nowhere <nowhere@noplace.org>
+
+	   This is just a sample commit comment, just for reference purposes.
+
+	   This "patch" does nothing.
+
+	   Signed-off-by: nowhere <nowhere@noplace.org>
+
+   All lines starting with # and all lines starting with HG: will be
+   removed from the mercurial commit log.
+
+   *WARNING* Be careful not to leave the first line blank, otherwise hg
+   will leave subject blank.
+
+   From: line shouldn't be omitted, since it will be used for the
+   patch author when converting to -git.
+
+c) For "make commit" to work properly, the HGUSER shell environment var
+   should be defined (replacing the names at the left):
+
+	HGUSER="My Name <myemail@mysite.com>"
+
+   If HGUSER is not set, then, if present, the username defined in the
+   user's ~/.hgrc file will be used.  Use of the .hgrc file is preferred
+   over the HGUSER variable according to the hg man page.
+
+   This name will be used for both the user metadata in the Hg commit
+   log and the initial values of the "From:" and "Signed-off-by:" lines
+   in the pre-made commit message.
+
+   It is also possible to use a different login name at the site
+   hosting the repository, by using:
+
+	CHANGE_LOG_LOGIN=my_log_name
+
+   With this, "make push" will use my_log_name, instead of the name for
+   the current Unix user.
+
+   Don't forget to export the vars at shell, with something like:
+
+	export CHANGE_LOG_LOGIN HGUSER
+
+   It is strongly recommended to have those lines in .bashrc or .profile.
+
+d) All patches shall have a Developers Certificate of Origin
+   version 1.1 in the commit log or the email description, signed by the
+   patch authors, as postulated in the Linux Kernel source at:
+
+	Documentation/SubmittingPatches
+
+   This is done by adding Signed-off-by: fields to the commit message.
+
+   It is not acceptable to use fake signatures, e.g.:
+
+	Signed-off-by: Fake me <me@snakeoilcompany.com>
+
+   The email must be a valid one.
+   The author that is submitting the email should be at the button of
+   the author's signed-off-by (SOB) block. Other SOBs or Acked-by: will be
+   added at the bottom, marking that somebody else reviewed the patch.
+
+   Each person who is in the kernel patch submission chain (driver author
+   and/or driver maintainer, subsystem/core maintainers, etc) will
+   review each patch. If they agree, the patch will be added to their
+   trees and signed. Otherwise, they may comment on the patch, asking
+   for some review.
+
+e) Although not documented at kernel's Documentation/, a common kernel
+   practice is to use Acked-by: tag.
+
+   An Acked-by: tag usually means that the acked person didn't write the
+   patch, nor is in the chain responsible for sending the patch to
+   kernel, but tested or reviewed the patch and agreed that it was good.
+
+   A patch acked-by can be added at hg trees, if received by each tree
+   maintainer. It is also common to receive acks after having a patch
+   inserted at master repository. In this case, the ack will be added
+   only at -git tree.
+
+f)  If the patch also affects other parts of kernel (like Alsa
+    or i2c), it is required that, when submitting upstream, the patch
+    also goes to the maintainers of that subsystem. To do this, the
+    developer shall copy the interested parties.
+
+    At mercurial tree, this can be handled automatically by the LinuxTV
+    scripts, by using the cc: meta tag, together with the Signed-off-by
+    lines. Something like:
+
+	CC: someotherkerneldeveloper@someplace
+	Signed-off-by: nowhere <nowhere@noplace.org>
+
+    This way, when a patch arrives mercurial hg tree, a mailbomb script
+    will copy the proper interested parties.
+
+    When submitting a patch via e-mail, it is better to copy all interested
+    parties directly, by adding them as cc's to the email itself.
+
+    Please note that those changes generally require ack from the
+    other subsystem maintainers. So, the best practice is to first ask
+    for their acks, then commit to the development tree or send the
+    patch via email with their Acked-by: already included.
+
+g) Sometimes, mainstream changes affect the v4l-dvb tree, and mast be
+   backported to the v4l-dvb tree. This kind of commit to the mercurial
+   tree should follow the rules above and should also have the line:
+
+	kernel-sync:
+
+   Patches with this line will not be submitted upstream.
+
+h) Sometimes it is necessary to introduce some testing code inside a
+   module or remove parts that are not yet finished. Also, compatibility
+   tests may be required to provide backporting.
+
+   To allow compatibility tests, linux/version.h is automatically
+   included by the building system. This allows adding tests like:
+
+	#if LINUX_VERSION_CODE >= KERNEL_VERSION(2,5,0)
+	#include <linux/kthread.h>
+	#endif
+
+   It should be noticed, however, that an explicit inclusion of
+   linux/version.h is required if it is needed to use KERNEL_VERSION()
+   macro (this is required, for example, by V4L2 VIDIOC_QUERYCAP
+   ioctl), otherwise, the driver won't compile when submitted to kernel.
+
+   There are several compatibility procedures already defined
+   in "compat.h" file. If needed, it is better to include it after all
+   other kernel standard headers, and before any specific header
+   for that file. Something like:
+
+	#include <linux/kernel.h>
+	#include <linux/module.h>
+		...
+	#include <linux/videodev2.h>
+	#include <media/v4l2-common.h>
+
+	#include "compat.h"
+
+	#include "mydriver-header.h"
+
+should be included at the
+   files under v4l-dvb tree. This header also includes linux/version.h.
+
+   To include testing code, #if 0 or #if 1 may be used. If this code
+   is meant to go also to kernel, a comment with the word "keep" should
+   be used, e.g:
+
+    #if 0 /* keep */
+	or
+    #if 1 /* keep */
+
+   The kernel submit scripts will remove the compatibility codes, the
+   tests for specific kernel versions and the #if 0/1 that doesn't have
+   the "keep meta tag".
+
+   See the file v4l/scripts/gentree.pl for a more complete description
+   of what kind of code will be kept and what kind will be removed.
+
+i) To import contributed stuff to a developer's, a script is provided.
+   This allows an easy import of mbox-based patch emails.
+   This is done with:
+
+	./mailimport <mbox file>
+
+    For it to work properly, git tools need to be installed on the local
+    machine, since git has a gitimport script that is used by mailimport.
+    Also, hg has a feature, called mqueue, that allows having several patches
+    that can be applied/unapplied for testing. mailimport trusts on it to work,
+    so, this extension should be enabled for mailimport script to work.
+
+j) By submitting a patch to the subsystem maintainer, either via email
+   or via pull request, the patch author(s) are agreeing that the
+   submitted code will be added on Kernel, and that the submitted code
+   are being released as GPLv2. The author may grant additional licenses
+   to the submitted code (for example, using dual GPL/BSD) or GPLv2 or
+   later. If no specific clause are added, the added code will be
+   assumed as GPLv2 only.
+
+5. Knowing about newer patches committed at master hg repository
+   ============================================================
+
+There's a patchbomb script at linuxtv.org that will send one copy of
+each patch applied to -hg tree to:
+
+1) The subscribers of the linuxtv-commits mailing list, hosted on
+   linuxtv.org;
+
+2) The patch author (as stated on the From: field in the patch comments);
+
+3) The patch committer (the "user" at hg metadata);
+
+4) All people with Signed-off-by:, Acked-by:, or CC: metadata clause
+   in the patch's comment.
+
+If, for some reason, there's no "From:" metatag (or it is on the first
+line, instead of the second one), sometimes the script may fail, maybe
+filling patch authorship wrongly. So people should take care to properly
+commit patches with "From:".
+
+6. Patch handling for kernel submission
+   ====================================
+
+The subsystem maintainer, when preparing the kernel patches to be sent
+to mainstream (or to -mm series), uses some scripts and a manual
+procedure, based on a quilt-like procedure, where a patch series file is
+generated, and patches can be handled one by one. This means that -git
+patches can be properly fixed, when required, if not already sent to
+mainstream, to fulfill the best practices and resolve conflicts with
+other patches directly merged in mainstream.
+
+There's a delay between updating a patch at master and sending it to
+mainstream. During this period, it is possible to review a patch. The
+common situations are:
+
+1) If a patch at master tree receives an Acked-by:, this can be added at
+-git tree;
+
+2) If somebody fully nacks a patch applied at -hg, A reverse patch
+can be applied at -hg, and the original patch can be removed -git;
+
+3) If somebody partially nacks a patch or sends a reviewing patch,
+the -git patch may be a result of the merger of the two patches.
+
+By merging both patches at -git will allow avoiding storing unnecessary
+patch history details at -git and at Mainstream.
+
+Those changes will require some manual sync between -git and -hg, it is
+better to avoid those circumstances.
+
+During the procedure of generating kernel patches, the maintainer uses
+to do a diff between the kernel tree and v4l-dvb mercurial tree
+(without any backport code there). If there are discrepancies, a
+backport patch from mainstream to v4l-dvb is generally applied by the
+maintainer.
+
+7. Patch submission from the community
+   ===================================
+
+Patch submission is open to all the Free Software community. The general
+procedure to have a patch accepted in the v4l/dvb subsystem and in the
+kernel is the following:
+
+a. Post your patches to the corresponding mailing list for review and
+   test by other people.
+
+   For analog or core changes, the V4L mailing list is
+	video4linux-list on redhat.com
+
+   For DVB changes, the mailing list is
+	linux-dvb on linuxtv.org
+
+   PS.: Sending emails to DVB Mailing List requires subscription via
+	http://linuxtv.org/lists.php
+
+	V4L mailing list doesn't require subscription, although
+	  subscription is recommended.
+
+b. Use [PATCH] and a brief description in the email's subject.
+   This will help the LinuxTV team to better handle it.
+
+c. Please include a brief description in the headers of your
+   patch, like described above. Something like:
+
+	   This is just a sample commit comment, just for reference purposes.
+	   This does nothing.
+
+	   Signed-off-by nowhere <nowere@noplace.org>
+
+d. Every patch shall have a Developers Certificate of Origin and should
+   be submitted by one of its authors. All the patch authors should sign
+   it.
+
+e. People will eventually comment about the patch. In this case,
+   please fix problems and repeat until everyone is happy ;)
+
+f. If the patch is fixing an existing maintained driver, the
+   low-level driver maintainer will apply to his tree, and at some later
+   time, ask the subsystem maintainer to pull it.
+
+g. If it is a newer driver (not yet in one of the development trees),
+   please copy the subsystem maintainer.
+
+8. Identifying regressions with Mercurial
+   ======================================
+
+   The better way for you to identify regressions with Mercurial is to
+   use hg bisect. This is an extension provided with the current
+   mercurial versions. For it to work, you need to have the proper setup
+   at an hgrc file. To test if bisect is working, you can do:
+	hg bisect help
+
+   If Mercurial answers with
+	hg: unknown command 'bisect'
+
+   You will need to add the following lines to your ~/.hgrc file:
+	[extensions]
+	hgext.hbisect=/usr/lib/python2.5/site-packages/hgext/hbisect.py
+
+	(assuming that hbisect.py is installed under python2.5 default dir)
+
+   The first step is to initialize bisect for a newer regression testing
+   session. This is done with:
+	hg bisect init
+
+   If the bisect were previously initialized, you should, instead do:
+	hg bisect reset
+
+   Supposing that the latest kernel version have some regression, you
+   should do something like:
+	hg update -C
+
+   (This will clean any changes you had on your tree, and will update to
+    the latest patch)
+
+   Then, you will mark the latest version as "bad":
+	hg bisect bad
+
+   The next step is to find one version where the your board is properly
+   working. Supposing that review "4000" is ok, you would do:
+	hg update 4000
+
+   Test if the review is really ok. If so, you should mark it as good:
+	hg bisect good
+
+   If everything is ok, it should print something like:
+
+	Testing changeset 4481:a53c7904e47d (944 changesets remaining, ~9 tests)
+	405 files updated, 0 files merged, 8 files removed, 0 files unresolved
+
+   The above line shows that Mercurial selected another revision for you
+   to test. Redo your tests. If this version is ok, you would do:
+
+	hg bisect good
+
+   otherwise, if the version is broken, you should do:
+
+	hg bisect bad
 
-5.  Fix problems and repeat until everyone is happy ;)
+   This should be repeated until you have an answer like:
 
-6.  Maintainers will periodically submit changes to mainstream.
+	The first bad revision is:
+	changeset:   4593:26d1ce012c5e
+	user:        Someone <Someone@somewhere>
+	date:        Thu Feb 31 17:52:53 2006 -0300
+	summary:     This is the broken patch that we should find
 
-Mauro
-Mauro Carvalho Chehab <mchehab .at. linuxtv .dot. org>
+   If, in the middle of the process, you need to know on what revision
+      you are, you can do something like:
+	hg log -r `hg id|cut -d' ' -f 1`