Mercurial > mplayer.hg
annotate DOCS/tech/svn-howto.txt @ 18841:3f59edf39ea2
cosmetics
author | diego |
---|---|
date | Wed, 28 Jun 2006 17:03:16 +0000 |
parents | 3b42c599ea09 |
children | 6ff05923a028 |
rev | line source |
---|---|
2200 | 1 |
18660 | 2 About Subversion write access: |
3 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
2200 | 4 |
18705 | 5 Before everything else, you should know how to use Subversion properly. |
18840 | 6 Luckily Subversion comes with excellent documentation. |
11395
5484bc13e90a
Some notes about general CVS documentation added, new 'cvs admin' section
diego
parents:
9537
diff
changeset
|
7 |
18705 | 8 svn help |
18840 | 9 |
10 shows you the available subcommands, | |
11 | |
12 svn help <command> | |
11395
5484bc13e90a
Some notes about general CVS documentation added, new 'cvs admin' section
diego
parents:
9537
diff
changeset
|
13 |
18840 | 14 shows information about the subcommand <command>. |
15 | |
16 The most comprehensive manual is the book "Version Control with Subversion" | |
17 by Ben Collins-Sussman, Brian W. Fitzpatrick and C. Michael Pilato. It can | |
18 be viewed online at | |
11395
5484bc13e90a
Some notes about general CVS documentation added, new 'cvs admin' section
diego
parents:
9537
diff
changeset
|
19 |
18705 | 20 http://svnbook.org/ |
11395
5484bc13e90a
Some notes about general CVS documentation added, new 'cvs admin' section
diego
parents:
9537
diff
changeset
|
21 |
18705 | 22 For more information about the Subversion project, visit |
11395
5484bc13e90a
Some notes about general CVS documentation added, new 'cvs admin' section
diego
parents:
9537
diff
changeset
|
23 |
18705 | 24 http://subversion.tigris.org/ |
11395
5484bc13e90a
Some notes about general CVS documentation added, new 'cvs admin' section
diego
parents:
9537
diff
changeset
|
25 |
5484bc13e90a
Some notes about general CVS documentation added, new 'cvs admin' section
diego
parents:
9537
diff
changeset
|
26 Consult these resources whenever you have problems, they are quite exhaustive. |
18840 | 27 |
28 What follows now is a basic introduction to Subversion and some MPlayer-specific | |
29 guidelines. Read it at least once, if you are granted commit privileges to the | |
30 MPlayer project you are expected to be familiar with these rules. | |
11395
5484bc13e90a
Some notes about general CVS documentation added, new 'cvs admin' section
diego
parents:
9537
diff
changeset
|
31 |
7904
98168d30f67d
Spellchecked, reworded, reformatted, small additions and corrections.
diego
parents:
5415
diff
changeset
|
32 |
18841 | 33 |
18840 | 34 I. BASICS: |
35 ========== | |
36 | |
37 1. Checking out the source tree: | |
7904
98168d30f67d
Spellchecked, reworded, reformatted, small additions and corrections.
diego
parents:
5415
diff
changeset
|
38 |
18840 | 39 svn checkout svn://svn.mplayerhq.hu/mplayer/trunk/ <target> |
2200 | 40 |
18840 | 41 This will put the MPlayer sources into the directory <target>. |
2200 | 42 |
18841 | 43 |
18840 | 44 2. Updating the source tree to the latest revision: |
18706 | 45 |
46 svn update | |
12024 | 47 |
18840 | 48 pulls in the latest changes from the repository to your working directory. |
49 | |
18841 | 50 |
18840 | 51 3. Adding/removing files/directories: |
52 | |
53 svn add <filename/dirname> | |
54 svn delete <filename/dirname> | |
55 | |
56 Subversion needs to get notified of all changes you make to your working | |
57 directory. | |
58 | |
18841 | 59 |
18840 | 60 4. Showing modifications: |
61 | |
62 svn diff <filename(s)> | |
63 | |
64 will show all local modifications in your working directory as unified diff. | |
65 | |
18841 | 66 |
18840 | 67 5. Inspecting the changelog: |
68 | |
69 svn log <filename(s)> | |
70 | |
71 You may also find viewvc, a web frontend for Subversion, helpful. It's often | |
72 more comfortable than using 'svn log' and 'svn diff'. Find it here: | |
73 http://svn.mplayerhq.hu/mplayer/trunk/ | |
74 | |
18841 | 75 |
18840 | 76 6. Checking source tree status: |
77 | |
78 svn status | |
79 | |
80 detects all the changes you made and lists what actions will be taken in case | |
81 of a commit (additions, modifications, deletions, etc.). | |
82 | |
18841 | 83 |
18840 | 84 7. Committing: |
2200 | 85 |
18767 | 86 svn update |
18840 | 87 |
88 Run 'svn update' before committing to make sure there were no changes to the | |
89 files you worked on in the meantime. Afterwards look at the output of | |
90 | |
91 svn diff <filename(s)> | |
12024 | 92 |
18840 | 93 to doublecheck your changes before committing to avoid trouble later on. All |
94 experienced developers do this on each and every commit, no matter how small. | |
95 Every one of them has been saved from looking like a fool by this many times. | |
96 It's very easy for stray debug output or cosmetic modifications to slip in, | |
97 please avoid problems through this extra level of scrutiny. | |
98 | |
99 Once you have made sure everything is fine | |
100 | |
101 svn commit <filename(s)> | |
102 | |
103 propagates your stuff to the repository. If you have made several independent | |
104 changes, commit them separately, not at the same time. | |
105 | |
106 When prompted for a password, type the password you got assigned by the | |
107 project admins. By default, Subversion caches all authentication tokens. | |
108 This behaviour can be disabled by setting both 'store-passwords' and | |
18706 | 109 'store-auth-creds' to "no" in ~/.subversion/config. You might need to remove |
110 previous cache files, which are located in ~/.subversion/auth, by hand. | |
12024 | 111 |
18840 | 112 You will be prompted for a log message in an editor, which is either specified |
113 by --editor-cmd on the command line, set in your personal configuration file | |
114 (~/.subversion/config) or set by one of the following environment variables: | |
115 SVN_EDITOR, VISUAL or EDITOR. | |
12024 | 116 |
18840 | 117 Log messages should be concise but descriptive. Explain why you made a change, |
118 what you did will be obvious from the changes themselves most of the time. | |
119 Saying just "bug fix" or "10l" is bad. Remember that people of varying skill | |
120 levels look at and educate themselves while reading through your code. Don't | |
121 include filenames in log messages, Subversion provides that information. | |
18706 | 122 |
18841 | 123 |
18840 | 124 8. Renaming/moving files or contents of files: |
13288 | 125 |
18840 | 126 svn move <source> <destination> |
127 svn commit <source> <destination> | |
2200 | 128 |
18706 | 129 Do not move or rename files before discussing it on the mplayer-dev-eng |
130 mailing list first! | |
2200 | 131 |
7904
98168d30f67d
Spellchecked, reworded, reformatted, small additions and corrections.
diego
parents:
5415
diff
changeset
|
132 Don't do a lot of cut'n'paste from one file to another without a very good |
98168d30f67d
Spellchecked, reworded, reformatted, small additions and corrections.
diego
parents:
5415
diff
changeset
|
133 reason and discuss it on the mplayer-dev-eng mailing list first. It will make |
18840 | 134 those changes hard to trace. |
5415 | 135 |
7904
98168d30f67d
Spellchecked, reworded, reformatted, small additions and corrections.
diego
parents:
5415
diff
changeset
|
136 Such actions are useless and treated as cosmetics in 99% of cases, |
98168d30f67d
Spellchecked, reworded, reformatted, small additions and corrections.
diego
parents:
5415
diff
changeset
|
137 so try to avoid them. |
11395
5484bc13e90a
Some notes about general CVS documentation added, new 'cvs admin' section
diego
parents:
9537
diff
changeset
|
138 |
18841 | 139 |
11395
5484bc13e90a
Some notes about general CVS documentation added, new 'cvs admin' section
diego
parents:
9537
diff
changeset
|
140 9. Reverting broken commits |
5484bc13e90a
Some notes about general CVS documentation added, new 'cvs admin' section
diego
parents:
9537
diff
changeset
|
141 |
18706 | 142 There is no Subversion equivalent of the 'cvs admin -o' command. Instead, |
143 be very careful about what you commit! If somehow you broke something, | |
144 revert the changes locally and re-commit with a proper commit message. | |
18840 | 145 You may want to use 'svn cat -r<revision> <filename>' to inspect an older |
18706 | 146 revision. |
15227
167085fd11af
'cvs admin -o' is dangerous and should be handled with extra care.
diego
parents:
14856
diff
changeset
|
147 |
18841 | 148 |
18840 | 149 10. Reverting local changes |
11395
5484bc13e90a
Some notes about general CVS documentation added, new 'cvs admin' section
diego
parents:
9537
diff
changeset
|
150 |
18840 | 151 svn revert <filename(s)> |
14806
6abe4fb845ff
mphq uses ssh.com, explain RSA key generation for it.
diego
parents:
14059
diff
changeset
|
152 |
18706 | 153 In case you made a lot of local changes to a file and want to start over |
18840 | 154 with a fresh checkout of that file, you can use 'svn revert <filename(s)>'. |
18706 | 155 NOTE: This has nothing to do with reverting changes on the Subversion |
156 server! It only reverts changes that were not committed yet. If you need | |
157 to revert a broken commit, see 9. | |
11395
5484bc13e90a
Some notes about general CVS documentation added, new 'cvs admin' section
diego
parents:
9537
diff
changeset
|
158 |
18841 | 159 |
18840 | 160 11. Changing commit messages |
18764
5b89070daa50
add command for changing commit messages after the commit took place.
ivo
parents:
18706
diff
changeset
|
161 |
5b89070daa50
add command for changing commit messages after the commit took place.
ivo
parents:
18706
diff
changeset
|
162 svn propedit svn:log --revprop -r <revision> |
5b89070daa50
add command for changing commit messages after the commit took place.
ivo
parents:
18706
diff
changeset
|
163 |
5b89070daa50
add command for changing commit messages after the commit took place.
ivo
parents:
18706
diff
changeset
|
164 If your commit message is too short or not explanatory enough, you can edit |
18840 | 165 it afterwards with svn' propedit'. |
18764
5b89070daa50
add command for changing commit messages after the commit took place.
ivo
parents:
18706
diff
changeset
|
166 |
18841 | 167 |
18840 | 168 Contact the project admins <root at mplayerhq dot hu> if you have technical |
18706 | 169 problems with the Subversion server. |
7904
98168d30f67d
Spellchecked, reworded, reformatted, small additions and corrections.
diego
parents:
5415
diff
changeset
|
170 |
2200 | 171 |
172 | |
173 II. POLICY / RULES: | |
174 =================== | |
175 | |
13288 | 176 1. You must not commit code which breaks MPlayer! (Meaning unfinished but |
7904
98168d30f67d
Spellchecked, reworded, reformatted, small additions and corrections.
diego
parents:
5415
diff
changeset
|
177 enabled code which breaks compilation or compiles but does not work.) |
13288 | 178 You can commit unfinished stuff (for testing etc), but it must be disabled |
179 (#ifdef etc) by default so it does not interfere with other developers' | |
180 work. | |
2200 | 181 |
18841 | 182 |
7904
98168d30f67d
Spellchecked, reworded, reformatted, small additions and corrections.
diego
parents:
5415
diff
changeset
|
183 2. You don't have to over-test things. If it works for you, and you think it |
98168d30f67d
Spellchecked, reworded, reformatted, small additions and corrections.
diego
parents:
5415
diff
changeset
|
184 should work for others, too, then commit. If your code has problems |
98168d30f67d
Spellchecked, reworded, reformatted, small additions and corrections.
diego
parents:
5415
diff
changeset
|
185 (portability, exploits compiler bugs, unusual environment etc) they will be |
98168d30f67d
Spellchecked, reworded, reformatted, small additions and corrections.
diego
parents:
5415
diff
changeset
|
186 reported and eventually fixed. |
2200 | 187 |
18841 | 188 |
13288 | 189 3. Do not commit unrelated changes together, split them into self-contained |
190 pieces. | |
2200 | 191 |
18841 | 192 |
17578 | 193 4. Do not change behavior of the program (renaming options etc) or |
17579
f1ce086b5eed
Clarify feature removal policy: it must be approved on the mailing list.
rathann
parents:
17578
diff
changeset
|
194 remove functionality from the code without approval in a discussion on |
f1ce086b5eed
Clarify feature removal policy: it must be approved on the mailing list.
rathann
parents:
17578
diff
changeset
|
195 the mplayer-dev-eng mailing list. |
12024 | 196 |
18841 | 197 |
13288 | 198 5. Do not commit changes to the build system (Makefiles, configure script) |
199 which change behaviour, defaults etc, without asking first. The same | |
200 applies to compiler warning fixes, trivial looking fixes and to code | |
201 maintained by other developers. We usually have a reason for doing things | |
202 the way we do. Send your changes as patches to the mplayer-dev-eng mailing | |
203 list, and if the code maintainers say OK, you may commit. This does not | |
204 apply to files you wrote and/or maintain. | |
205 | |
18841 | 206 |
13288 | 207 6. We refuse source indentation and other cosmetic changes if they are mixed |
208 with functional changes, such commits will be rejected and removed. Every | |
209 developer has his own indentation style, you should not change it. Of course | |
210 if you (re)write something, you can use your own style... (Many projects | |
211 force a given indentation style - we don't.) If you really need to make | |
212 indentation changes (try to avoid this), separate them strictly from real | |
213 changes. | |
12024 | 214 |
215 NOTE: If you had to put if(){ .. } over a large (> 5 lines) chunk of code, | |
13288 | 216 do NOT change the indentation of the inner part (don't move it to the right)! |
2200 | 217 |
18841 | 218 |
13288 | 219 7. Always fill out the commit log message. Describe in a few lines what you |
220 changed and why. You can refer to mailing list postings if you fix a | |
221 particular bug. Comments such as "fixed!" or "Changed it." are unacceptable. | |
2200 | 222 |
18841 | 223 |
13288 | 224 8. If you apply a patch by someone else, include the name and email address in |
18660 | 225 the log message. Since the mplayer-cvslog mailing list is publicly |
13288 | 226 archived you should add some spam protection to the email address. Send an |
227 answer to mplayer-dev-eng (or wherever you got the patch from) saying that | |
17054 | 228 you applied the patch. If the patch contains a documentation change, commit |
229 that as well; do not leave it to the documentation maintainers. | |
2200 | 230 |
18841 | 231 |
13288 | 232 9. Do NOT commit to code actively maintained by others without permission. Send |
233 a patch to mplayer-dev-eng instead. | |
12107
bc89ddda34b8
Developers should subscribe to mplayer-cvslog, mention mplayer-docs.
diego
parents:
12099
diff
changeset
|
234 |
18841 | 235 |
18660 | 236 10. Subscribe to the mplayer-cvslog mailing list. The diffs of all commits |
12107
bc89ddda34b8
Developers should subscribe to mplayer-cvslog, mention mplayer-docs.
diego
parents:
12099
diff
changeset
|
237 are sent there and reviewed by all the other developers. Bugs and possible |
bc89ddda34b8
Developers should subscribe to mplayer-cvslog, mention mplayer-docs.
diego
parents:
12099
diff
changeset
|
238 improvements or general questions regarding commits are discussed there. We |
bc89ddda34b8
Developers should subscribe to mplayer-cvslog, mention mplayer-docs.
diego
parents:
12099
diff
changeset
|
239 expect you to react if problems with your code are uncovered. |
12024 | 240 |
18841 | 241 |
13288 | 242 11. Update the documentation if you change behavior or add features. If you are |
243 unsure how best to do this, send a patch to mplayer-docs, the documentation | |
244 maintainers will review and commit your stuff. | |
245 | |
18841 | 246 |
12099 | 247 Also read DOCS/tech/patches.txt !!!! |
5415 | 248 |
7904
98168d30f67d
Spellchecked, reworded, reformatted, small additions and corrections.
diego
parents:
5415
diff
changeset
|
249 We think our rules are not too hard. If you have comments, contact us. |
98168d30f67d
Spellchecked, reworded, reformatted, small additions and corrections.
diego
parents:
5415
diff
changeset
|
250 |
98168d30f67d
Spellchecked, reworded, reformatted, small additions and corrections.
diego
parents:
5415
diff
changeset
|
251 |
3258 | 252 |
18827 | 253 III. Beginners Guide |
3258 | 254 ==================== |
18828 | 255 |
256 The typical flow of development would be: | |
257 | |
258 1. Check out the source: | |
259 | |
260 svn checkout svn://svn.mplayerhq.hu/mplayer/trunk/ devel | |
261 | |
18841 | 262 |
18828 | 263 2. Make your changes. |
264 | |
18841 | 265 |
18828 | 266 3. Create a patch: |
267 | |
18840 | 268 Run 'svn diff' from the root of the source tree, like this: |
18828 | 269 |
270 cd devel | |
271 svn diff > ../my_changes.patch | |
272 | |
273 If you have made several changes, but only want to submit one for review | |
274 by other developers, you can specify the filename(s), for example: | |
275 | |
276 svn diff mplayer.c > ../major_cleanup.patch | |
277 | |
18841 | 278 |
18828 | 279 4. Check the patch: |
280 | |
281 Check out another, clean source tree and verify your patch: | |
282 | |
283 svn checkout svn://svn.mplayerhq.hu/mplayer/trunk/ clean | |
284 cd clean | |
285 patch -p0 --dry-run < ../my_changes.patch | |
286 | |
287 If there are no errors, you can apply your patch: | |
288 | |
289 patch -p0 < ../my_changes.patch | |
290 | |
291 After that, verify that MPlayer still builds correctly with your patch | |
292 applied. Also, be sure that your patch meets our policy as described in | |
293 section II, specifically rules 1 to 6, before you continue submitting | |
294 the patch. | |
295 | |
18841 | 296 |
18828 | 297 5. Submit the patch: |
298 | |
299 Send an e-mail to the mplayer-dev-eng mailing list. Describe what your | |
300 patch does and why, and attach the patch file for review by others. | |
301 | |
18841 | 302 |
18828 | 303 6. During the review process, incorporate all suggested fixes. Go to step 2 |
304 repeatedly until there is nothing more to do for step 6. Of course, if | |
305 you don't agree with certain suggestions, things can be discussed on | |
306 the mailing list in a polite manner. | |
307 | |
18841 | 308 |
18828 | 309 7. Commit the patch: |
310 | |
311 If your patch is accepted, double check if your source tree contains the | |
18840 | 312 most recent version of your patch with 'svn diff'! After verifying that |
313 you met these conditions, commit with: | |
18828 | 314 |
18840 | 315 svn commit <filename(s)> |
18828 | 316 |
317 Go to step 2 ad infinitum until MPlayer is the perfect media player ;) | |
318 | |
18841 | 319 |
18828 | 320 Note: If you are listed as the maintainer for a particular piece of code, |
321 you can skip step 5 and 6 if your patch _only_ applies to the code you | |
322 maintain. If it touches other code or is otherwise very intrusive, please | |
323 post it to mplayer-dev-eng first. |