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
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
|
About Subversion write access:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Before everything else, you should know how to use Subversion properly.
Subversion comes with some documentation.
svn help
man svn
info svn
are a good start. The most comprehensive manual is the book "Version Control
with Subversion" by Ben Collins-Sussman, Brian W. Fitzpatrick and C. Michael
Pilato. It can be viewed online at
http://svnbook.org/
For more information about the Subversion project, visit
http://subversion.tigris.org/
Consult these resources whenever you have problems, they are quite exhaustive.
What follows now are MPlayer specific guidelines.
I. TECH SIDE:
=============
1. Checking out development source tree:
svn checkout svn://svn.mplayerhq.hu/mplayer/trunk/
2. Updating source tree to latest revision:
svn update
3. Committing changes:
svn update
svn commit --username USERNAME filename(s)
Do not use comments such as: "bug fix." or "files changed" or "dunno".
You don't have to include the filename in the comment, as comments are linked
to files. If you have made several independent changes, commit them
separately, not at the same time. You will be prompted for a comment in an
editor, which is either specified by --editor-cmd on the command line, set
in your personal configuration file (~/.subversion/config) or set by one of
the following environment variables: SVN_EDITOR, VISUAL or EDITOR. When
prompted for a password, type the password you got assigned by the Subversion
server admin. By default, Subversion caches all authentication tokens. This
behaviour can be disabled by setting both 'store-passwords' and
'store-auth-creds' to "no" in ~/.subversion/config. You might need to remove
previous cache files, which are located in ~/.subversion/auth, by hand.
4. Adding new files/directories:
svn add filename/dirname
svn commit filename/dirname
5. Removing files:
svn delete filename
svn commit filename
6. Checking changes:
svn diff filename(s)
Doublecheck your changes before committing to avoid trouble later on.
This way you will see if your patch has debug stuff or indentation
changes and you can fix it before committing and triggering flames.
7. Checking changelog:
svn log filename(s)
You may also find viewvc, a web frontend for Subversion, helpful. It's often
more comfortable than using svn log and svn diff. Find it here:
http://svn.mplayerhq.hu/mplayer/trunk/
8. Renaming/moving files or content of files:
svn move source destination
svn commit source destination
Do not move or rename files before discussing it on the mplayer-dev-eng
mailing list first!
Don't do a lot of cut'n'paste from one file to another without a very good
reason and discuss it on the mplayer-dev-eng mailing list first. It will make
those changes untraceable!
Such actions are useless and treated as cosmetics in 99% of cases,
so try to avoid them.
9. Reverting broken commits
There is no Subversion equivalent of the 'cvs admin -o' command. Instead,
be very careful about what you commit! If somehow you broke something,
revert the changes locally and re-commit with a proper commit message.
You may want to use 'svn cat -r<revision> filename' to inspect an older
revision.
10. Checking status of source tree
svn status
This will detect all the changes you made and list what actions will be
taken in case of a commit (Additions, Modifications, Deletions, et cetera).
11. Reverting local changes
svn revert filename(s)
In case you made a lot of local changes to a file and want to start over
with a fresh checkout of that file, you can use svn revert filename(s).
NOTE: This has nothing to do with reverting changes on the Subversion
server! It only reverts changes that were not committed yet. If you need
to revert a broken commit, see 9.
12. Changing commit messages
svn propedit svn:log --revprop -r <revision>
If your commit message is too short or not explanatory enough, you can edit
it afterwards with svn propedit.
Contact the project admin <root at mplayerhq dot hu> if you have technical
problems with the Subversion server.
II. POLICY / RULES:
===================
1. You must not commit code which breaks MPlayer! (Meaning unfinished but
enabled code which breaks compilation or compiles but does not work.)
You can commit unfinished stuff (for testing etc), but it must be disabled
(#ifdef etc) by default so it does not interfere with other developers'
work.
2. You don't have to over-test things. If it works for you, and you think it
should work for others, too, then commit. If your code has problems
(portability, exploits compiler bugs, unusual environment etc) they will be
reported and eventually fixed.
3. Do not commit unrelated changes together, split them into self-contained
pieces.
4. Do not change behavior of the program (renaming options etc) or
remove functionality from the code without approval in a discussion on
the mplayer-dev-eng mailing list.
5. Do not commit changes to the build system (Makefiles, configure script)
which change behaviour, defaults etc, without asking first. The same
applies to compiler warning fixes, trivial looking fixes and to code
maintained by other developers. We usually have a reason for doing things
the way we do. Send your changes as patches to the mplayer-dev-eng mailing
list, and if the code maintainers say OK, you may commit. This does not
apply to files you wrote and/or maintain.
6. We refuse source indentation and other cosmetic changes if they are mixed
with functional changes, such commits will be rejected and removed. Every
developer has his own indentation style, you should not change it. Of course
if you (re)write something, you can use your own style... (Many projects
force a given indentation style - we don't.) If you really need to make
indentation changes (try to avoid this), separate them strictly from real
changes.
NOTE: If you had to put if(){ .. } over a large (> 5 lines) chunk of code,
do NOT change the indentation of the inner part (don't move it to the right)!
7. Always fill out the commit log message. Describe in a few lines what you
changed and why. You can refer to mailing list postings if you fix a
particular bug. Comments such as "fixed!" or "Changed it." are unacceptable.
8. If you apply a patch by someone else, include the name and email address in
the log message. Since the mplayer-cvslog mailing list is publicly
archived you should add some spam protection to the email address. Send an
answer to mplayer-dev-eng (or wherever you got the patch from) saying that
you applied the patch. If the patch contains a documentation change, commit
that as well; do not leave it to the documentation maintainers.
9. Do NOT commit to code actively maintained by others without permission. Send
a patch to mplayer-dev-eng instead.
10. Subscribe to the mplayer-cvslog mailing list. The diffs of all commits
are sent there and reviewed by all the other developers. Bugs and possible
improvements or general questions regarding commits are discussed there. We
expect you to react if problems with your code are uncovered.
11. Update the documentation if you change behavior or add features. If you are
unsure how best to do this, send a patch to mplayer-docs, the documentation
maintainers will review and commit your stuff.
Also read DOCS/tech/patches.txt !!!!
We think our rules are not too hard. If you have comments, contact us.
III. Beginners Guide
====================
The typical flow of development would be:
1. Check out the source:
svn checkout svn://svn.mplayerhq.hu/mplayer/trunk/ devel
2. Make your changes.
3. Create a patch:
Run svn diff from the root of the source tree, like this:
cd devel
svn diff > ../my_changes.patch
If you have made several changes, but only want to submit one for review
by other developers, you can specify the filename(s), for example:
svn diff mplayer.c > ../major_cleanup.patch
4. Check the patch:
Check out another, clean source tree and verify your patch:
svn checkout svn://svn.mplayerhq.hu/mplayer/trunk/ clean
cd clean
patch -p0 --dry-run < ../my_changes.patch
If there are no errors, you can apply your patch:
patch -p0 < ../my_changes.patch
After that, verify that MPlayer still builds correctly with your patch
applied. Also, be sure that your patch meets our policy as described in
section II, specifically rules 1 to 6, before you continue submitting
the patch.
5. Submit the patch:
Send an e-mail to the mplayer-dev-eng mailing list. Describe what your
patch does and why, and attach the patch file for review by others.
6. During the review process, incorporate all suggested fixes. Go to step 2
repeatedly until there is nothing more to do for step 6. Of course, if
you don't agree with certain suggestions, things can be discussed on
the mailing list in a polite manner.
7. Commit the patch:
If your patch is accepted, double check if your source tree contains the
most recent version of your patch with svn diff! After verifying that you
met these conditions, commit with:
svn commit filename(s)
Go to step 2 ad infinitum until MPlayer is the perfect media player ;)
Note: If you are listed as the maintainer for a particular piece of code,
you can skip step 5 and 6 if your patch _only_ applies to the code you
maintain. If it touches other code or is otherwise very intrusive, please
post it to mplayer-dev-eng first.
|