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>

1 files changed, 448 insertions, 35 deletions

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`