Mauro Carvalho Chehab wrote:
> 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.
Mauro,
A few issues... #1, I think we're better off keeping this document called
README.patches, as we have already directed users on the mailing lists to this
file, and those emails remain indexed in google forever. IMHO, better to stay
consistent.
#2, I have made some corrections to the document. Please see these corrections
inline below.
Regards,
Michael Krufky
>
>
>
> ------------------------------------------------------------------------
>
> 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
^ involved in
> +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
^introduction
> + ==========================================
> +
> +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
^ was
> +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
^ v4l
> +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
^^^ Michael Krufky
> +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 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
^ v4l
> +maintainer, available at:
> + http://linuxtv.org/hg/v4l-dvb
> +
> +When a developer believes that he have patches done to be merged, he
^ has
> +send a request to developers ML and to the subsystem maintainer. The
^sends
> +patches are analised and, if they look ok, merged at the master
^ analyzed
> +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
^^^ top
> + 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,
^^ and signed.
> + 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,
^write
> + 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.
^ When submitting a patch via email, it is better to copy all interested
parties diretcly, by adding them as cc's to the email itself.
> +
> + Please notice that those changes generally requires ack from the
^ note require an 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
^to
> + 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,
^ on the
> + since git have a gitimport script that is used by mailimport.
^ has
> + Also, hg have a feature, called mqueue, that allows having several patches
^ hasZ
> + 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
^handled ^This
> +patches can be properly fixed, when required, if not already sent to
> +mainstream, to futhfill the best practices and resolve conflicts with
^fulfill
> +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
^ uses what?
> +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
^ s/"driver"/""/2
> + 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
