diff options
Diffstat (limited to 'README.HG')
| -rw-r--r-- | README.HG | 163 |
1 files changed, 163 insertions, 0 deletions
diff --git a/README.HG b/README.HG new file mode 100644 index 000000000..0f114b340 --- /dev/null +++ b/README.HG @@ -0,0 +1,163 @@ +Mauro Carvalho Chehab 2006 Jan 28 + + This file describes general procedures used by v4l-dvb +maintainers. Some of these also applies to patch submitters. + + We've moved from cvs to a modern SCM system that fits better +into kernel development model, called Mercurial (aka hg). + + hg 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. + + It is strongly recommended that every developer use a local copy +of the repository to make their own tests and use one or more tags for his +own needs. + + Mercurial is a developer database, It means that it might be +broken from time to time, although all efforts should be done to avoid this. +There are more "stable" snapshots at http://www.linuxtv.org/downloads/snapshot +page. + + This file postulates some simple rules for maintaing hg tree, +as stated bellow: + + 1) It is strongly recommended that hg maintainers 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) Minor changes, like simple card additions (for example a new card +row at a card struct) can be applied directly by the hg maintainer; + + 3) Medium changes that needs modification on card coding or +creating a new card type should be discussed first at the Mailing Lists +video4linux-list .at. redhat .dot. com (analog/common parts) and/or +linux-dvb .at. linuxtv .dot. org to allow other contributors to discuss +about the way it will be included. + + 4) Major changes that implies changing some core structs should +be widely discussed on IRC, posted to the list, created a snapshot THEN +committed to the tip branch. It is strongly recommended to use a branch +or v4l_experimental area for such changes. + + 5) The v4l-dvb maintainer should be warned to create a snapshot +if the changes could generate impacts on other cards BEFORE commiting +the change to the tip tag; + + 6) Every CVS maintainer should follow the "rules of thumb" of kernel +development stated at Linux source code, especially: + Documenation/SubmittingPatches + Documentation/SubmittingDrivers + Documentation/CodingStyle + + 7) Non active CVS maintainers or that ones who doesn't like to follow +these rules may be dropped. + + 8) Every commit should update ChangeLog describing who did, what +changed and in what files, by using the command: + make changes + + 9) The latest changelog line will be automatically used as a prototype +to the commit message at the local repository by using: + make commit + + 10) if commit go 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. + + 11) To update master repository, it is needed to do: + make pull + + 12) For hg to work properly, these vars should be defined (replacing the +names at the left): + +CHANGE_LOG_NAME="Maintainer Name" +CHANGE_LOG_EMAIL_ADDRESS=maintainer-email@cvsmaintainersite.com +CHANGE_LOG_LOGIN=my_log_name + +HGUSER=$CHANGE_LOG_NAME +export CHANGE_LOG_NAME CHANGE_LOG_EMAIL_ADDRESS CHANGE_LOG_LOGIN HGUSER + + It is recommended to have these lines at .bashrc or .profile. + + 13) All commit messages shall have a Developers Certificate of Origin +version 1.1 at Changelog and cvs 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 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 CVS maintainer. + + This is an example of ChangeLog entry: + + 2005-06-28 18:35 cvsmaintainer + * filelist.c, filelist.h: + - described changes. + + Signed-off-by: Patch Developer <patchdeveloper@patchdevelopersite.com> + Signed-off-by: Cvs Maintainer <cvsmaintainer@cvsmaintainersite.com> + + Obs.: Timestamp should be in GMT. + + 14) Commit messages are very rellevant, 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> + + 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. + From: shouldn't be suppressed + You may add other signers, if the patch were tested by somebody +else and he also wants to sign. The commiter signed-off-by should be the last one. + + 15) If the patch also affects other parts of kernel (like alsa +or i2c), it is required that, at upstream submiting, the patch also go +to the maintainers of that subsystem. To do this, CVS maintainer shall add +one or more cc: fields at 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. + + 16) 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 submited upstream. + + 17) sometimes, it is necessary to introduce some testing code +inside a module or remove parts that are not yet finished. Also, +compatibility tests maybe 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 shuld be used: +#if 0 /* keep */ + or +#if 1 /* keep */ + + 18) Nested #ifs are allowed, but #elsif 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. + +Cheers, +Mauro + +Mauro Carvalho Chehab <mchehab .at. linuxtv .dot. org> |