1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
|
Mauro Carvalho Chehab 2006 Jan 30
This file describes the 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).
At http://selenic.com/mercurial you'll find quick-start info, a
tutorial and FAQs.
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.
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.
The v4l-dvb mercurial repository is meant for development. 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
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) Minor changes, like simple card additions (for example a new card
row at a card struct) can be applied directly by each developer;
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@redhat.com (analog/common parts) and/or
linux-dvb@linuxtv.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) Every CVS maintainer 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 bellow.
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
*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 *MASTER* repository you need to run:
make push
10) To update from the master repository, it is needed to do:
make pull
11) 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.
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@snakeoilcompany.com>
The email should be a valid one.
The bottom signed-off-by should be the commiter.
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@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.
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.
Cheers,
Mauro
Mauro Carvalho Chehab <mchehab .at. linuxtv .dot. org>
|
