Hi Guys, The last time we've reviewed our procedures were on March, 2006. I think it is time to review the documents (there's still an even more ancient file, from 2005!). I'm enclosing a file, with my understanding on the current practices for V4L/DVB development. Please comment. -- Cheers, Mauro
diff -r 299dd4a8b598 README.development --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/README.development Tue Mar 06 13:43:13 2007 -0200 @@ -0,0 +1,337 @@ +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 envolved on V4L/DVB +drivers. They are a volunteer, non-remunerated, 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 introdution 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 were 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 related 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 + +Mike Krufky maintains a number of backport trees, having 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 + +3. Mercurial trees used on v4l/dvb development + =========================================== + +V4L/DVB driver development is hosted at http://linuxtv.org. There are a +number of trees there, owned by each developer of the LinuxTV team. Each +developer use to keep and maintain one or more trees there with their +development stuff. + +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 have patches done to be merged, he +send a request to developers ML and to the subsystem maintainer. The +patches are analised and, if they look ok, merged at the master +repository. + +It is a good practice that each developer will have at least one tree +called 'v4l-dvb', keeping their stable patches, periodically updating +his tree with master's patches. + +4. Community best practices + ======================== + +From the 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 will check changed files, seeking for + bad whitespace practices and will 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, the patch author's + name at the second line, and a brief description, with no more than + 80 chars by line, like: + + 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 # will be removed by make commit stripts. + + *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 the patch author. + +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>" + + 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 of + 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 at .bashrc or .profile. + +d) All patches shall have a Developers Certificate of Origin + version 1.1 at commit log or email description, signed by the + patch authors, 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 author that submitted the + patch. + + Each one that is at 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 on their + trees and signed by they. Otherwise, they may comment the patch, + asking for some review. + +e) Although not documented at kernel's Documentation/, a common kernel + practice is to use Acked-by: meta tag. + + An Acked-by usually means that the acked person didn't wrote the patch, + nor is at the chain responsible to send the patch to kernel, but + tested or reviewed it and agrees that the patch is 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, at upstream submitting, 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, the better is to direclty the + interested people add at email's CC field. + + Please notice that those changes generally requires ack from the + other subsystem maintainers. So, the best practice is to first ask + their acks, then commit at the development tree or send it via email + already with a proper Acked-by: + +g) Sometimes, mainstream changes do affect v4l-dvb tree, and requires + to backport some kernel patches at the tree. This kind of commit + at mercurial tree should follow the rules above and should also have + a line like: + + kernel-sync: + + Patches with such lines 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, "compat.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, this struct should be used: + + #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". + +i) To import contributed stuff on a developers tree, on mercurial a + script is provided at the tree. This allows an 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. + +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 video4linux-cvs@xxxxxxxxxxx mailing list (*); + +2) the patch author (as stated at From: field at the middle of the + comments); + +3) to the patch committer (the "user" at hg metadata); + +4) to all people with Signed-off-by:, Acked-by:, or CC: metadata clause + at the patch's comment. + +If, for some reason, there's no "From:" metatag (or it is at the first +line, instead of the second one), sometimes the script may fail, maybe +filling patch authorship wrongly. So people should take care of properly +committing 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 handles one by one. It means that -git +patches can be properly fixed, when required, if not already sent to +mainstream, to futhfill the best practices and resolve conflicts with +other patches direclty 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 Free Software community. The general +procedure to have a patch accepted at v4l/dvb subsystem and at 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 at 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 + driver maintainer will apply on his tree, asking the subsystem + maintainer to pull, after some time. + +g. If it is a newer driver (not yet on one of the development trees), + please copy the subsystem maintainer. diff -r 299dd4a8b598 README.HG --- a/README.HG Mon Mar 05 10:32:29 2007 +0100 +++ /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> diff -r 299dd4a8b598 README.patches --- a/README.patches Mon Mar 05 10:32:29 2007 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,58 +0,0 @@ -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: - 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>
_______________________________________________ linux-dvb mailing list linux-dvb@xxxxxxxxxxx http://www.linuxtv.org/cgi-bin/mailman/listinfo/linux-dvb
