Michael and Trent, Thanks for your comments. I've took the best suggestions from both of you. The enclosed patch contains a reviewed patch. I'm also commenting a few stuff under Trent's email. Em Ter, 2007-03-06 às 13:29 -0800, Trent Piepho escreveu: > > > + 80 chars by line, like: > ^per ^e.g. > > [Should we have the make commit script check the line length limits?] On CVS, we had a script, enforced at the server side, that used to check for some stuff (From: SOB:, etc). I think it is a good idea to have a check script for it. > 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. I'm not sure if the scripts will handle .hgrc users properly. Can you check it, please (It should to, but I'm not 100% if this is working ok) ? > [Is there anyway to add an ack without deleting and re-creating the tree?] Yes, with hg strip, but this will mean that the patch changeset (a MD5 hash) will change. So, this shouldn't be done at master tree (otherwise, people will need to remove the patches from their trees and re-add the changed version). This is one reason for using master v4l-dvb as a "draft" tree with the patches, having the definitive versions, with all acks and SOBs at -git. You should notice that I can't even sign the patches imported from other trees on v4l-dvb hg without altering its hash. I do sign they on -git. > > > + inserted at master repository. In this case, the ack will be added > > > + only at -git tree. > > [How does one record that the v4l subsytem maintainer should add these acks?] This is done manually. As soon as I receive such acks, I run my import scripts for -git, add at the patches there (on my local machine), and include the proper Ack. All to avoid the risk of forgetting the acks... > ^a line > > > > +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, "compat.h" should be included at the > > > + files under v4l-dvb tree. This header also includes linux/version.h. > > [This is not true anymore. linux/version.h is included via the build system > cflags, it is not necessary to include "compat.h" to use a kernel version test. > Is it best if compat.h is included after all <*.h> includes and before any "*.h" > includes.] Ok, I've reviewed the text, adding some more useful info for developers. Cheers, Mauro
diff -r f71d56dfeb0d README.patches --- a/README.patches Wed Mar 07 12:28:33 2007 -0200 +++ b/README.patches Wed Mar 07 16:44:05 2007 -0200 @@ -1,58 +1,375 @@ Mauro Carvalho Chehab 2005 Dec 02 -Mauro Carvalho Chehab 2005 Dec 02 - - The master copy of the video4linux and dvb kernel subsystem is now -maintained jointly at http://linuxtv.org/ - -=== v4l-dvb snapshots available at linuxtv.org - - 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: - -http://linuxtv.org/downloads/snapshots - -=== v4l-dvb quilt available at linuxtv.org - - It is also available patches against latest development kernel at: -http://linuxtv.org/downloads/quilt - - patches/series shows the correct order to apply. - -== Getting the latest Snapshot - - 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: - -hg clone http://linuxtv.org/hg/v4l-dvb - -* Patches should be built against v4l-dvb master Hg repository. - -=== How to get your changes into the mainline tree? - -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@xxxxxxxxxxx For DVB changes, the mailing list -is linux-dvb@xxxxxxxxxxxx The latest requires subscription. -http://linuxtv.org/lists.php - -2. Using [PATCH] at subject will help maintainers to better handle it. - -3. Please include a ChangeLog description in the headers of your patch. - -4. Every patch shall have a Developers Certificate of Origin like - -Signed-off-by: Your name <name@xxxxxxxxxxxx> - -with name of people envolving on making it. - - This should be a real name and address. The exact meaning of the -signed-off-by is postulated at linux source code, at file: +Mauro Carvalho Chehab <mchehab at infradead dot org> +2007 Mar 6 + +This file describes the general procedures used by the LinuxTV team (*) +and by the v4l-dvb community. + +(*) 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 Webcams, Analog TV, Digital +TV and radio broadcast AM/FM. + +1. A Brief introduction about patch management + ========================================== + +Current V4L/DVB development is based on a modern SCM system that +fits better into kernel development model, called Mercurial (aka hg). + +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. + +There are some tutorials, FAQs and other valuable informations at +http://selenic.com/mercurial about hg usage. + +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 + +2. Git trees' relationships with v4l/dvb development + ================================================= + +The main kernel trees are hosted at http://git.kernel.org. Each tree +is owned by a maintainer. + +The main kernel tree is owned by Linus Torvalds, being located at: + http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git + +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 + +Michael Krufky maintains a number of backport trees, which have patches +contained at the subsystem master tree that are needed to fix some known +issues on previous kernel versions, also at + http://git.kernel.org/http://git.kernel.org/?p=linux/kernel/git/mkrufky/v4l-dvb-2.6.x.y.git + +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. + +There is also a master mercurial repository, owned by the subsystem +maintainer, available at: + http://linuxtv.org/hg/v4l-dvb + +When a developer believes that he has patches done to be merged, he +sends a request tthe developers' mailing list and to the subsystem +maintainer. The patches are analized 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 - -5. Fix problems and repeat until everyone is happy ;) - -6. Maintainers will periodically submit changes to mainstream. - -Mauro -Mauro Carvalho Chehab <mchehab .at. linuxtv .dot. org> + 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: nowere <nowere@xxxxxxxxxxx> + + This is just a sample commit comment, just for reference purposes. + + This "patch" does nothing. + + Signed-off-by: nowere <nowere@xxxxxxxxxxx> + + 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 ommited, 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@xxxxxxxxxx>" + + 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 repo, 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@xxxxxxxxxxxxxxxxxxx> + + The email must be a valid one. + The author that is submitting the email should be at the botton of + the author's signed-off-by (SOB) block. Other SOBs or Acked-by: will be + added at the botton, 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: nowere <nowere@xxxxxxxxxxx> + + 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 direclty, by adding tmem 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 developers'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. + +5. Knowing about newer patches commited 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 video4linux-cvs@xxxxxxxxxxx mailing list (*); + +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:". + +(*) Yes, we know that this is really a very bad name for this + list, since: + a) We don't use CVS anymore; + b) The script will post at this list any HG patches applied to + the main hg trees, including dvb-apps and v4l-dvb patches. + +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 mailing list is + video4linux-list@xxxxxxxxxx + + For DVB changes, the mailing list is + linux-dvb@xxxxxxxxxxxx + + PS.: Sending emails to DVB Mailing List requires subscription via + http://linuxtv.org/lists.php + +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 nowere <nowere@xxxxxxxxxxx> + +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 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. diff -r f71d56dfeb0d README.HG --- a/README.HG Wed Mar 07 12:28:33 2007 -0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -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@xxxxxxxxxx (analog/common parts) - and/or linux-dvb@xxxxxxxxxxx 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@xxxxxxxxxxxxxxxxxxxxx>" - - 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@xxxxxxxxxxxxxxxxxxx> - - 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@xxxxxxxxxxxxxxxxxxxxxx> - - patch descriptions - - Signed-off-by: Patch Developer <patchdeveloper@xxxxxxxxxxxxxxxxxxxxxx> - Signed-off-by: Cvs Maintainer <cvsmaintainer@xxxxxxxxxxxxxxxxxxxxx> - - 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>
_______________________________________________ linux-dvb mailing list linux-dvb@xxxxxxxxxxx http://www.linuxtv.org/cgi-bin/mailman/listinfo/linux-dvb
