Difference between revisions of "Maintaining Mercurial (Hg) trees"

From LinuxTVWiki
Jump to: navigation, search
(move quotations (one to submitting patches article; other to "Development Section" portal page))
 
(13 intermediate revisions by 8 users not shown)
Line 1: Line 1:
CVS is a developer database, It means that it might be broken from time to time. There are more "stable" snapshots at [http://www.linuxtv.org/downloads/video4linux/ v4l downloads page].
+
== The history of VCS for v4l ==
  
These are some simple rules that gives some directions for maintaing CVS tree:
+
Up until 2006-01-30, the source code for the v4l kernel modules was available via CVS; cf. [http://linuxtv.org/cgi-bin/viewcvs.cgi/?root=v4l v4l CVS root]. There are old snapshots available from  [http://www.linuxtv.org/downloads/video4linux/ June to November 2005]. Before that, the code was housed at [http://dl.bytesex.org/patches/ Gerd Knorr's site].
  
1) Every CVS maintainer should be active at [irc://irc.freenode.net/v4l #V4L IRC channel]. It helps
+
As of 2006-01-30, V4L and DVB kernel modules are available via [http://www.selenic.com/mercurial/wiki/index.cgi Mercurial], a lightweight Source Control Management system. See the current [http://linuxtv.org/repo/ instructions for source access].
to have more discussions at major changes;
+
  
2) Minor changes, like simple card additions (only a card row at card
+
Starting on 2010-01-23, the main tree is maintained via git SCM, being available at [http://linuxtv.org/git Linuxtv git trees], following the procedures adopted on the other Linux Kernel drivers. The patches on git are backported to the mercurial tree.
struct) can be applied directly for the CVS maintainer;
+
  
3) Medium changes that needs modification on card coding or creating a
+
The instructions to maintain the git trees are available at the [[Maintaining_Git_trees | maintaining git trees]] page.
new card type should be discussed at [irc://irc.freenode.net/v4l #V4L IRC channel] to allow other
+
contributors to discuss about the way it will be included. V4L
+
maintainer should be warned to create a snapshot (if the change could
+
generate impacts on other cards) BEFORE commiting the change to CVS;
+
  
4) Major changes that implies changing some core structs should be
+
== Notes for maintainers ==
discussed on IRC, posted to the list, created a snapshot THEN committed
+
to CVS.
+
  
  5) Every CVS maintainer should follow the "rules of thumb" of kernel
+
(See also file README.HG in the sources)
development like:
+
* [[SubmittingPatches | Kernel rules to submit patches]]
+
* [[Documentation/SubmittingDrivers | Kernel rules to submit drivers]]
+
* [[Documentation/CodingStyle | Kernel Coding Style]]
+
  
6) People interested in being a CVS maintainer should participate at IRC,
+
Current V4L/DVB tree uses a modern SCM system that fits better into
before requesting changing access to V4L CVS.
+
kernel development model, called Mercurial (aka hg).
  
7) Non active CVS maintainers or that doesn't like to follow the above
+
There are some tutorials, FAQs and other valuable informations at
rules may be dropped.
+
http://selenic.com/mercurial
  
        8) Every commit should update ChangeLog describing who did, what changed and in what files.
+
Mercurial is a distributed SCM, which means every developer gets his
It should also have [[ SubmittingPatches#Developer.27s_Certificate_of_Origin_1.1|Developer's Certificate of Origin 1.1 ]] for each patch contributor.
+
own full copy of the repository (including the complete revision
The bottom signed-off-by should be the CVS maintainer.
+
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:
 +
 
 +
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;
 +
 
 +
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.
 +
 
 +
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.
 +
 
 +
Medium or major changes that needs modification on card coding, creating a new card type or requiring changes at core structs should be discussed first at the Mailing Lists video4linux-list@redhat.com (analog/common parts)  and/or linux-dvb@linuxtv.org and at IRC to allow other contributors to discuss about the way it will be included.
 +
 
 +
Every developer should follow the "rules of thumb" of kernel development stated at Linux source code, especially:
 +
 
 +
* Documentation/SubmittingPatches
 +
* Documentation/SubmittingDrivers
 +
* Documentation/CodingStyle
 +
 
 +
All commits should have a consistent message. On v4l-dvb, this is  done by using:
 
   
 
   
  This is an example:
+
  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 bellow.
 +
 
 +
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>]
 +
 
 +
<b>Warning</b> hg addremove will add/removes all files, including object files. Be careful! You can remove wrongly added files with hg remove.
 +
 
 +
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.
 +
 
 +
To push the change to the repository you need to run:
 +
 
 +
hg push <url>
 +
 
 +
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
 +
 
 +
For hg to work properly, these vars should be defined (replacing the names at the left):
 +
 
 +
HGUSER="Maintainer Name <maintainer-email@cvsmaintainersite.com>"
 +
 
 +
If you use a different login name at the repo, you may use:
 +
 
 +
CHANGE_LOG_LOGIN=my_log_name
 +
 
 +
You may also have it at ~/.hgrc, but, in this case, make commit will not generate From: and Signed-off-by fields automatically. Don't forget to export the vars, like:
 +
 
 +
export CHANGE_LOG_LOGIN HGUSER
 +
 
 +
It is strongly recommended to have these lines at .bashrc or .profile.
 +
 
 +
All commit messages shall have a Developers Certificate of Origin version 1.1 at commit log, as postulated at kernel's source at:
 +
 
 +
Documentation/SubmittingPatches
 +
 
 +
This is done by using Signed-off-by: fields at hg commit message.
 +
 
 +
It is not acceptable to use fake signatures like:
 +
 
 +
Signed-off-by: Fake me <me@snakeoilcompany.com>
 +
 
 +
The email should be a valid one. The bottom signed-off-by should be the commiter.
 
   
 
   
  2005-06-28 18:35  cvsmaintainer
+
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:
        * filelist.c, filelist.h:
+
 
        - described changes.
+
  patch subject
   
+
From: Patch Developer <patchdeveloper@patchdevelopersite.com>
        Signed-off-by: Patch Developer <patchdeveloper@patchdevelopersite.com>
+
 
        Signed-off-by: Cvs Maintainer <cvsmaintainer@cvsmaintainersite.com>
+
patch descriptions
   
+
 
  Obs.: Timestamp should be in GMT
+
Signed-off-by: Patch Developer <patchdeveloper@patchdevelopersite.com>
---
+
Signed-off-by: Cvs Maintainer <cvsmaintainer@cvsmaintainersite.com>
 +
 
 +
All lines starting with # will be removed by make commit stripts. Subject should be a brief description of the patch. Please notice that, with hg, there's no need (and not desired) to define a Subject: tag. The *first* msg line will be used as subject, just like git. *WARNING* Be careful not to leave the first line blank, otherwise hg will leave subject in blank.
 +
 
 +
  From: line shouldn't be suppressed, since it will be used when
 +
  converting to -git as patch author.
 +
 
 +
You may add other signers, if the patch were tested /co-developed by somebody else and he also wants to sign. The committer signed-off-by should be the last one.
 +
 
 +
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.
 +
 
 +
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.
 +
 
 +
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 */
 +
 
 +
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.
  
Some quotations about development:
+
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.
  
"The most difficult problem isn't fixing bugs, but fixing bugs
 
without breaking other configurations.  There are many: different
 
cards, different TV norms, whereas most of the developers can test
 
only one TV norm." - Gerd Knorr
 
  
  
"Anyone who has never made a mistake has never tried anything new." - Albert Einstein
+
[[Category:Development]]

Latest revision as of 19:59, 20 February 2012

The history of VCS for v4l

Up until 2006-01-30, the source code for the v4l kernel modules was available via CVS; cf. v4l CVS root. There are old snapshots available from June to November 2005. Before that, the code was housed at Gerd Knorr's site.

As of 2006-01-30, V4L and DVB kernel modules are available via Mercurial, a lightweight Source Control Management system. See the current instructions for source access.

Starting on 2010-01-23, the main tree is maintained via git SCM, being available at Linuxtv git trees, following the procedures adopted on the other Linux Kernel drivers. The patches on git are backported to the mercurial tree.

The instructions to maintain the git trees are available at the maintaining git trees page.

Notes for maintainers

(See also file README.HG in the sources)

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:

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;

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.

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.

Medium or major changes that needs modification on card coding, creating a new card type or requiring changes at core structs should be discussed first at the Mailing Lists video4linux-list@redhat.com (analog/common parts) and/or linux-dvb@linuxtv.org and at IRC to allow other contributors to discuss about the way it will be included.

Every developer should follow the "rules of thumb" of kernel development stated at Linux source code, especially:

  • Documentation/SubmittingPatches
  • Documentation/SubmittingDrivers
  • Documentation/CodingStyle

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 bellow.

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.

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.

To push the change to the repository you need to run:

hg push <url>

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

For hg to work properly, these vars should be defined (replacing the names at the left):

HGUSER="Maintainer Name <maintainer-email@cvsmaintainersite.com>"

If you use a different login name at the repo, you may use:

CHANGE_LOG_LOGIN=my_log_name

You may also have it at ~/.hgrc, but, in this case, make commit will not generate From: and Signed-off-by fields automatically. Don't forget to export the vars, like:

export CHANGE_LOG_LOGIN HGUSER

It is strongly recommended to have these lines at .bashrc or .profile.

All commit messages shall have a Developers Certificate of Origin version 1.1 at commit log, as postulated at kernel's source at:

Documentation/SubmittingPatches

This is done by using Signed-off-by: fields at hg commit message.

It is not acceptable to use fake signatures like:

Signed-off-by: Fake me <me@snakeoilcompany.com>

The email should be a valid one. The bottom signed-off-by should be the commiter.

Commit messages are very relevant, since they will be used when generating the patches for v4l-dvb.git and to mainstream. The format of commit message shall be:

patch subject
From: Patch Developer <patchdeveloper@patchdevelopersite.com>

patch descriptions

Signed-off-by: Patch Developer <patchdeveloper@patchdevelopersite.com>
Signed-off-by: Cvs Maintainer <cvsmaintainer@cvsmaintainersite.com>

All lines starting with # will be removed by make commit stripts. Subject should be a brief description of the patch. Please notice that, with hg, there's no need (and not desired) to define a Subject: tag. The *first* msg line will be used as subject, just like git. *WARNING* Be careful not to leave the first line blank, otherwise hg will leave subject in blank.

From: line shouldn't be suppressed, since it will be used when 
converting to -git as patch author.

You may add other signers, if the patch were tested /co-developed by somebody else and he also wants to sign. The committer signed-off-by should be the last one.

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.

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.

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 */

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.

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.