Mercurial > mplayer.hg
annotate DOCS/tech/svn-howto.txt @ 18828:55ebe20fadbc
Add new Subversion beginners guide
author | ivo |
---|---|
date | Mon, 26 Jun 2006 19:04:59 +0000 |
parents | 67f847c438bd |
children | 3b42c599ea09 |
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. |
6 Subversion comes with some documentation. | |
11395
5484bc13e90a
Some notes about general CVS documentation added, new 'cvs admin' section
diego
parents:
9537
diff
changeset
|
7 |
18705 | 8 svn help |
9 man svn | |
10 info svn | |
11395
5484bc13e90a
Some notes about general CVS documentation added, new 'cvs admin' section
diego
parents:
9537
diff
changeset
|
11 |
18705 | 12 are a good start. The most comprehensive manual is the book "Version Control |
13 with Subversion" by Ben Collins-Sussman, Brian W. Fitzpatrick and C. Michael | |
14 Pilato. It can be viewed online at | |
11395
5484bc13e90a
Some notes about general CVS documentation added, new 'cvs admin' section
diego
parents:
9537
diff
changeset
|
15 |
18705 | 16 http://svnbook.org/ |
11395
5484bc13e90a
Some notes about general CVS documentation added, new 'cvs admin' section
diego
parents:
9537
diff
changeset
|
17 |
18705 | 18 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
|
19 |
18705 | 20 http://subversion.tigris.org/ |
11395
5484bc13e90a
Some notes about general CVS documentation added, new 'cvs admin' section
diego
parents:
9537
diff
changeset
|
21 |
5484bc13e90a
Some notes about general CVS documentation added, new 'cvs admin' section
diego
parents:
9537
diff
changeset
|
22 Consult these resources whenever you have problems, they are quite exhaustive. |
5484bc13e90a
Some notes about general CVS documentation added, new 'cvs admin' section
diego
parents:
9537
diff
changeset
|
23 What follows now are MPlayer specific guidelines. |
5484bc13e90a
Some notes about general CVS documentation added, new 'cvs admin' section
diego
parents:
9537
diff
changeset
|
24 |
7904
98168d30f67d
Spellchecked, reworded, reformatted, small additions and corrections.
diego
parents:
5415
diff
changeset
|
25 |
2200 | 26 I. TECH SIDE: |
27 ============= | |
7904
98168d30f67d
Spellchecked, reworded, reformatted, small additions and corrections.
diego
parents:
5415
diff
changeset
|
28 |
18706 | 29 1. Checking out development source tree: |
2200 | 30 |
18706 | 31 svn checkout svn://svn.mplayerhq.hu/mplayer/trunk/ |
2200 | 32 |
18706 | 33 2. Updating source tree to latest revision: |
34 | |
35 svn update | |
12024 | 36 |
7904
98168d30f67d
Spellchecked, reworded, reformatted, small additions and corrections.
diego
parents:
5415
diff
changeset
|
37 3. Committing changes: |
2200 | 38 |
18767 | 39 svn update |
18706 | 40 svn commit --username USERNAME filename(s) |
12024 | 41 |
7904
98168d30f67d
Spellchecked, reworded, reformatted, small additions and corrections.
diego
parents:
5415
diff
changeset
|
42 Do not use comments such as: "bug fix." or "files changed" or "dunno". |
98168d30f67d
Spellchecked, reworded, reformatted, small additions and corrections.
diego
parents:
5415
diff
changeset
|
43 You don't have to include the filename in the comment, as comments are linked |
12099 | 44 to files. If you have made several independent changes, commit them |
13288 | 45 separately, not at the same time. You will be prompted for a comment in an |
18706 | 46 editor, which is either specified by --editor-cmd on the command line, set |
47 in your personal configuration file (~/.subversion/config) or set by one of | |
48 the following environment variables: SVN_EDITOR, VISUAL or EDITOR. When | |
49 prompted for a password, type the password you got assigned by the Subversion | |
50 server admin. By default, Subversion caches all authentication tokens. This | |
51 behaviour can be disabled by setting both 'store-passwords' and | |
52 'store-auth-creds' to "no" in ~/.subversion/config. You might need to remove | |
53 previous cache files, which are located in ~/.subversion/auth, by hand. | |
12024 | 54 |
18767 | 55 4. Adding new files/directories: |
2200 | 56 |
18706 | 57 svn add filename/dirname |
18767 | 58 svn commit filename/dirname |
12024 | 59 |
2200 | 60 5. Removing files: |
61 | |
18706 | 62 svn delete filename |
63 svn commit filename | |
12024 | 64 |
7904
98168d30f67d
Spellchecked, reworded, reformatted, small additions and corrections.
diego
parents:
5415
diff
changeset
|
65 6. Checking changes: |
12024 | 66 |
18706 | 67 svn diff filename(s) |
12024 | 68 |
13288 | 69 Doublecheck your changes before committing to avoid trouble later on. |
70 This way you will see if your patch has debug stuff or indentation | |
71 changes and you can fix it before committing and triggering flames. | |
12024 | 72 |
7904
98168d30f67d
Spellchecked, reworded, reformatted, small additions and corrections.
diego
parents:
5415
diff
changeset
|
73 7. Checking changelog: |
2200 | 74 |
18706 | 75 svn log filename(s) |
76 | |
77 You may also find viewvc, a web frontend for Subversion, helpful. It's often | |
78 more comfortable than using svn log and svn diff. Find it here: | |
79 http://svn.mplayerhq.hu/mplayer/trunk/ | |
13288 | 80 |
18706 | 81 8. Renaming/moving files or content of files: |
12024 | 82 |
18706 | 83 svn move source destination |
84 svn commit source destination | |
2200 | 85 |
18706 | 86 Do not move or rename files before discussing it on the mplayer-dev-eng |
87 mailing list first! | |
2200 | 88 |
7904
98168d30f67d
Spellchecked, reworded, reformatted, small additions and corrections.
diego
parents:
5415
diff
changeset
|
89 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
|
90 reason and discuss it on the mplayer-dev-eng mailing list first. It will make |
98168d30f67d
Spellchecked, reworded, reformatted, small additions and corrections.
diego
parents:
5415
diff
changeset
|
91 those changes untraceable! |
5415 | 92 |
7904
98168d30f67d
Spellchecked, reworded, reformatted, small additions and corrections.
diego
parents:
5415
diff
changeset
|
93 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
|
94 so try to avoid them. |
11395
5484bc13e90a
Some notes about general CVS documentation added, new 'cvs admin' section
diego
parents:
9537
diff
changeset
|
95 |
5484bc13e90a
Some notes about general CVS documentation added, new 'cvs admin' section
diego
parents:
9537
diff
changeset
|
96 9. Reverting broken commits |
5484bc13e90a
Some notes about general CVS documentation added, new 'cvs admin' section
diego
parents:
9537
diff
changeset
|
97 |
18706 | 98 There is no Subversion equivalent of the 'cvs admin -o' command. Instead, |
99 be very careful about what you commit! If somehow you broke something, | |
100 revert the changes locally and re-commit with a proper commit message. | |
101 You may want to use 'svn cat -r<revision> filename' to inspect an older | |
102 revision. | |
15227
167085fd11af
'cvs admin -o' is dangerous and should be handled with extra care.
diego
parents:
14856
diff
changeset
|
103 |
18706 | 104 10. Checking status of source tree |
12025
124734dc7c66
Explain why 'cvs admin' should only be used on the last revision of a file.
diego
parents:
12024
diff
changeset
|
105 |
18706 | 106 svn status |
11395
5484bc13e90a
Some notes about general CVS documentation added, new 'cvs admin' section
diego
parents:
9537
diff
changeset
|
107 |
18706 | 108 This will detect all the changes you made and list what actions will be |
109 taken in case of a commit (Additions, Modifications, Deletions, et cetera). | |
11395
5484bc13e90a
Some notes about general CVS documentation added, new 'cvs admin' section
diego
parents:
9537
diff
changeset
|
110 |
18706 | 111 11. Reverting local changes |
14806
6abe4fb845ff
mphq uses ssh.com, explain RSA key generation for it.
diego
parents:
14059
diff
changeset
|
112 |
18706 | 113 svn revert filename(s) |
14806
6abe4fb845ff
mphq uses ssh.com, explain RSA key generation for it.
diego
parents:
14059
diff
changeset
|
114 |
18706 | 115 In case you made a lot of local changes to a file and want to start over |
116 with a fresh checkout of that file, you can use svn revert filename(s). | |
117 NOTE: This has nothing to do with reverting changes on the Subversion | |
118 server! It only reverts changes that were not committed yet. If you need | |
119 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
|
120 |
18764
5b89070daa50
add command for changing commit messages after the commit took place.
ivo
parents:
18706
diff
changeset
|
121 12. Changing commit messages |
5b89070daa50
add command for changing commit messages after the commit took place.
ivo
parents:
18706
diff
changeset
|
122 |
5b89070daa50
add command for changing commit messages after the commit took place.
ivo
parents:
18706
diff
changeset
|
123 svn propedit svn:log --revprop -r <revision> |
5b89070daa50
add command for changing commit messages after the commit took place.
ivo
parents:
18706
diff
changeset
|
124 |
5b89070daa50
add command for changing commit messages after the commit took place.
ivo
parents:
18706
diff
changeset
|
125 If your commit message is too short or not explanatory enough, you can edit |
5b89070daa50
add command for changing commit messages after the commit took place.
ivo
parents:
18706
diff
changeset
|
126 it afterwards with svn propedit. |
5b89070daa50
add command for changing commit messages after the commit took place.
ivo
parents:
18706
diff
changeset
|
127 |
14856 | 128 Contact the project admin <root at mplayerhq dot hu> if you have technical |
18706 | 129 problems with the Subversion server. |
7904
98168d30f67d
Spellchecked, reworded, reformatted, small additions and corrections.
diego
parents:
5415
diff
changeset
|
130 |
2200 | 131 |
132 | |
133 II. POLICY / RULES: | |
134 =================== | |
135 | |
13288 | 136 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
|
137 enabled code which breaks compilation or compiles but does not work.) |
13288 | 138 You can commit unfinished stuff (for testing etc), but it must be disabled |
139 (#ifdef etc) by default so it does not interfere with other developers' | |
140 work. | |
2200 | 141 |
7904
98168d30f67d
Spellchecked, reworded, reformatted, small additions and corrections.
diego
parents:
5415
diff
changeset
|
142 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
|
143 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
|
144 (portability, exploits compiler bugs, unusual environment etc) they will be |
98168d30f67d
Spellchecked, reworded, reformatted, small additions and corrections.
diego
parents:
5415
diff
changeset
|
145 reported and eventually fixed. |
2200 | 146 |
13288 | 147 3. Do not commit unrelated changes together, split them into self-contained |
148 pieces. | |
2200 | 149 |
17578 | 150 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
|
151 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
|
152 the mplayer-dev-eng mailing list. |
12024 | 153 |
13288 | 154 5. Do not commit changes to the build system (Makefiles, configure script) |
155 which change behaviour, defaults etc, without asking first. The same | |
156 applies to compiler warning fixes, trivial looking fixes and to code | |
157 maintained by other developers. We usually have a reason for doing things | |
158 the way we do. Send your changes as patches to the mplayer-dev-eng mailing | |
159 list, and if the code maintainers say OK, you may commit. This does not | |
160 apply to files you wrote and/or maintain. | |
161 | |
162 6. We refuse source indentation and other cosmetic changes if they are mixed | |
163 with functional changes, such commits will be rejected and removed. Every | |
164 developer has his own indentation style, you should not change it. Of course | |
165 if you (re)write something, you can use your own style... (Many projects | |
166 force a given indentation style - we don't.) If you really need to make | |
167 indentation changes (try to avoid this), separate them strictly from real | |
168 changes. | |
12024 | 169 |
170 NOTE: If you had to put if(){ .. } over a large (> 5 lines) chunk of code, | |
13288 | 171 do NOT change the indentation of the inner part (don't move it to the right)! |
2200 | 172 |
13288 | 173 7. Always fill out the commit log message. Describe in a few lines what you |
174 changed and why. You can refer to mailing list postings if you fix a | |
175 particular bug. Comments such as "fixed!" or "Changed it." are unacceptable. | |
2200 | 176 |
13288 | 177 8. If you apply a patch by someone else, include the name and email address in |
18660 | 178 the log message. Since the mplayer-cvslog mailing list is publicly |
13288 | 179 archived you should add some spam protection to the email address. Send an |
180 answer to mplayer-dev-eng (or wherever you got the patch from) saying that | |
17054 | 181 you applied the patch. If the patch contains a documentation change, commit |
182 that as well; do not leave it to the documentation maintainers. | |
2200 | 183 |
13288 | 184 9. Do NOT commit to code actively maintained by others without permission. Send |
185 a patch to mplayer-dev-eng instead. | |
12107
bc89ddda34b8
Developers should subscribe to mplayer-cvslog, mention mplayer-docs.
diego
parents:
12099
diff
changeset
|
186 |
18660 | 187 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
|
188 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
|
189 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
|
190 expect you to react if problems with your code are uncovered. |
12024 | 191 |
13288 | 192 11. Update the documentation if you change behavior or add features. If you are |
193 unsure how best to do this, send a patch to mplayer-docs, the documentation | |
194 maintainers will review and commit your stuff. | |
195 | |
12099 | 196 Also read DOCS/tech/patches.txt !!!! |
5415 | 197 |
7904
98168d30f67d
Spellchecked, reworded, reformatted, small additions and corrections.
diego
parents:
5415
diff
changeset
|
198 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
|
199 |
98168d30f67d
Spellchecked, reworded, reformatted, small additions and corrections.
diego
parents:
5415
diff
changeset
|
200 |
3258 | 201 |
18827 | 202 III. Beginners Guide |
3258 | 203 ==================== |
18828 | 204 |
205 The typical flow of development would be: | |
206 | |
207 1. Check out the source: | |
208 | |
209 svn checkout svn://svn.mplayerhq.hu/mplayer/trunk/ devel | |
210 | |
211 2. Make your changes. | |
212 | |
213 3. Create a patch: | |
214 | |
215 Run svn diff from the root of the source tree, like this: | |
216 | |
217 cd devel | |
218 svn diff > ../my_changes.patch | |
219 | |
220 If you have made several changes, but only want to submit one for review | |
221 by other developers, you can specify the filename(s), for example: | |
222 | |
223 svn diff mplayer.c > ../major_cleanup.patch | |
224 | |
225 4. Check the patch: | |
226 | |
227 Check out another, clean source tree and verify your patch: | |
228 | |
229 svn checkout svn://svn.mplayerhq.hu/mplayer/trunk/ clean | |
230 cd clean | |
231 patch -p0 --dry-run < ../my_changes.patch | |
232 | |
233 If there are no errors, you can apply your patch: | |
234 | |
235 patch -p0 < ../my_changes.patch | |
236 | |
237 After that, verify that MPlayer still builds correctly with your patch | |
238 applied. Also, be sure that your patch meets our policy as described in | |
239 section II, specifically rules 1 to 6, before you continue submitting | |
240 the patch. | |
241 | |
242 5. Submit the patch: | |
243 | |
244 Send an e-mail to the mplayer-dev-eng mailing list. Describe what your | |
245 patch does and why, and attach the patch file for review by others. | |
246 | |
247 6. During the review process, incorporate all suggested fixes. Go to step 2 | |
248 repeatedly until there is nothing more to do for step 6. Of course, if | |
249 you don't agree with certain suggestions, things can be discussed on | |
250 the mailing list in a polite manner. | |
251 | |
252 7. Commit the patch: | |
253 | |
254 If your patch is accepted, double check if your source tree contains the | |
255 most recent version of your patch with svn diff! After verifying that you | |
256 met these conditions, commit with: | |
257 | |
258 svn commit filename(s) | |
259 | |
260 Go to step 2 ad infinitum until MPlayer is the perfect media player ;) | |
261 | |
262 Note: If you are listed as the maintainer for a particular piece of code, | |
263 you can skip step 5 and 6 if your patch _only_ applies to the code you | |
264 maintain. If it touches other code or is otherwise very intrusive, please | |
265 post it to mplayer-dev-eng first. |