Mercurial > mplayer.hg
annotate DOCS/tech/new_policy_proposal.txt @ 22592:c3501315b4d0
update >5 line reindention rule to what is in ffmpeg
author | michael |
---|---|
date | Thu, 15 Mar 2007 12:47:20 +0000 |
parents | e27b971ccae5 |
children | 9a299c7e30b0 |
rev | line source |
---|---|
22368 | 1 New Policy Draft |
2 Version 20070301 | |
18840 | 3 |
22368 | 4 Intro: |
5 ------ | |
6 This document is an attempt to write a new policy as the old is fairly | |
22532 | 7 confusing and easy to misunderstand, its intention is not really to |
22368 | 8 change the rules but rather to write them down clearer ... |
9 also for simplicity and to prevent flamewars, i would suggest that you | |
10 fork this document and propose that fork as alternative if you have a | |
11 significant disagreement with me on some part | |
18841 | 12 |
22368 | 13 Author: |
14 ------- | |
15 Michael Niedermayer | |
22530 | 16 the authors of the old policy as I liberally copy and pasted from it |
18706 | 17 |
22368 | 18 TODO: |
22373 | 19 add more explanations, justifications and examples |
22368 | 20 how to become/loose maintainer status |
21 review patches.txt | |
22 security/exploit rules | |
23 ------------------------ | |
18840 | 24 |
18841 | 25 |
22368 | 26 1. Definitions |
27 -------------- | |
22373 | 28 * MPlayer developer, generally referred to simply as developer in this document |
22368 | 29 is any person who has a open (not cracked, not suspended) svn write account |
22382 | 30 * MPlayer leader, generally referred to simply as leader in this document, every |
31 leader is also a developer | |
22373 | 32 * CAN/MUST/SHOULD descriptions ... |
22368 | 33 * public developer mailing list (mplayer-dev-eng at mplayerhq in hungary) |
18840 | 34 |
18841 | 35 |
22368 | 36 C. Code and SVN Rules |
37 ----------------------------- | |
38 Renaming/moving/copying files or contents of files | |
19376 | 39 Do not move, rename or copy files of which you are not the maintainer without |
22368 | 40 discussing it on the public developer mailinglist first! |
19357
59af53f4f436
update the moving & copying rules as disscussed on mplayer-dev + some (but not all as iam lazy) fixes by the wanderer
michael
parents:
19248
diff
changeset
|
41 |
19376 | 42 Never copy or move a file by using 'svn delete' and 'svn add'. Always use |
43 'svn move' or 'svn copy' instead in order to preserve history and minimize | |
44 the size of diffs. | |
19357
59af53f4f436
update the moving & copying rules as disscussed on mplayer-dev + some (but not all as iam lazy) fixes by the wanderer
michael
parents:
19248
diff
changeset
|
45 |
19376 | 46 To split a file, use 'svn copy' and remove the unneeded lines from each file. |
2200 | 47 |
7904
98168d30f67d
Spellchecked, reworded, reformatted, small additions and corrections.
diego
parents:
5415
diff
changeset
|
48 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
|
49 reason and discuss it on the mplayer-dev-eng mailing list first. It will make |
18840 | 50 those changes hard to trace. |
5415 | 51 |
7904
98168d30f67d
Spellchecked, reworded, reformatted, small additions and corrections.
diego
parents:
5415
diff
changeset
|
52 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
|
53 so try to avoid them. |
11395
5484bc13e90a
Some notes about general CVS documentation added, new 'cvs admin' section
diego
parents:
9537
diff
changeset
|
54 |
22368 | 55 Reverting broken commits |
19382 | 56 There are 2 ways to reverse a change, they differ significantly in what they |
57 do to the svn repository | |
58 The recommit old method: | |
59 svn merge | |
60 svn ci <file> | |
61 This simply changes the file(s) back to their old version localy and then | |
62 the change is commited as if it is a new change | |
63 The svn copy method | |
64 svn rm <file> | |
65 svn ci <file> | |
66 svn cp -r<good revision> svn://svn.mplayerhq.hu/mplayer/trunk/[<path>/]<file> <file> | |
67 svn ci <file> | |
68 This simply removes the file and then copies the last good version with | |
69 its history over it, this method can only be used to revert the n last | |
70 commits but not to revert a bad commit in the middle of its history | |
71 Neither method will change the history, checking out an old version will | |
72 always return exactly that revision with all its bugs and features. The | |
73 difference is that with the svn copy method the broken commit will not be | |
22238 | 74 part of the directly visible history of the revisions after the reversal |
75 So if the change was completely broken like reindenting a file against the | |
76 maintainers decision, or a change which mixed functional and cosmetic | |
22345 | 77 changes then it is better if it is not part of the visible history as it |
19382 | 78 would make it hard to read, review and would also break svn annotate |
79 For the example of a change which mixed functional and cosmetic parts they | |
22238 | 80 should of course be committed again after the reversal but separately, so one |
19382 | 81 change with the functional stuff and one with the cosmetics |
82 OTOH if the change which you want to reverse was simply buggy but not | |
83 totally broken then it should be reversed with svn merge as otherwise | |
84 the fact that the change was bad would be hidden | |
85 One method to decide which reversal method is best is to ask yourself | |
22345 | 86 if there is any value in seeing the whole bad change and its removal |
87 in SVN vs just seeing a comment that says what has been reversed while | |
22238 | 88 the actual change does not clutter the immediately visible history and |
19382 | 89 svn annotate. |
90 If you are even just slightly uncertain how to revert something then ask on | |
22345 | 91 the mplayer-dev-eng mailing list. |
15227
167085fd11af
'cvs admin -o' is dangerous and should be handled with extra care.
diego
parents:
14856
diff
changeset
|
92 |
22368 | 93 Broken code |
94 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
|
95 enabled code which breaks compilation or compiles but does not work.) |
13288 | 96 You can commit unfinished stuff (for testing etc), but it must be disabled |
97 (#ifdef etc) by default so it does not interfere with other developers' | |
98 work. | |
2200 | 99 |
22368 | 100 Testing code |
101 You don't have to over-test things. If it works for you, and you think it | |
7904
98168d30f67d
Spellchecked, reworded, reformatted, small additions and corrections.
diego
parents:
5415
diff
changeset
|
102 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
|
103 (portability, exploits compiler bugs, unusual environment etc) they will be |
98168d30f67d
Spellchecked, reworded, reformatted, small additions and corrections.
diego
parents:
5415
diff
changeset
|
104 reported and eventually fixed. |
2200 | 105 |
22373 | 106 Splitting changes |
22368 | 107 Do not commit unrelated changes together, split them into self-contained |
22591
e27b971ccae5
update spliting rule to what i just added to ffmpeg
michael
parents:
22590
diff
changeset
|
108 pieces. Also dont forget that if part B depends on part A but A doesnt |
e27b971ccae5
update spliting rule to what i just added to ffmpeg
michael
parents:
22590
diff
changeset
|
109 depend on B, then A can and should be commited first and seperately from B. |
e27b971ccae5
update spliting rule to what i just added to ffmpeg
michael
parents:
22590
diff
changeset
|
110 Keeping changes well split into self contained parts makes reviewing and |
e27b971ccae5
update spliting rule to what i just added to ffmpeg
michael
parents:
22590
diff
changeset
|
111 understanding them on svn log at the time of commit and later when |
e27b971ccae5
update spliting rule to what i just added to ffmpeg
michael
parents:
22590
diff
changeset
|
112 debugging a bug much easier. |
e27b971ccae5
update spliting rule to what i just added to ffmpeg
michael
parents:
22590
diff
changeset
|
113 Also if you have doubt about spliting or not spliting, dont hesitate to |
e27b971ccae5
update spliting rule to what i just added to ffmpeg
michael
parents:
22590
diff
changeset
|
114 ask/disscuss it on the developer mailing list. |
18841 | 115 |
17578 | 116 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
|
117 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
|
118 the mplayer-dev-eng mailing list. |
12024 | 119 |
18841 | 120 |
13288 | 121 5. Do not commit changes to the build system (Makefiles, configure script) |
122 which change behaviour, defaults etc, without asking first. The same | |
123 applies to compiler warning fixes, trivial looking fixes and to code | |
124 maintained by other developers. We usually have a reason for doing things | |
125 the way we do. Send your changes as patches to the mplayer-dev-eng mailing | |
126 list, and if the code maintainers say OK, you may commit. This does not | |
127 apply to files you wrote and/or maintain. | |
128 | |
18841 | 129 |
22368 | 130 Cosmetics |
131 We refuse source indentation and other cosmetic changes if they are mixed | |
132 with functional changes, such commits will be reverted. Every | |
13288 | 133 developer has his own indentation style, you should not change it. Of course |
134 if you (re)write something, you can use your own style... (Many projects | |
135 force a given indentation style - we don't.) If you really need to make | |
136 indentation changes (try to avoid this), separate them strictly from real | |
137 changes. | |
12024 | 138 |
22592
c3501315b4d0
update >5 line reindention rule to what is in ffmpeg
michael
parents:
22591
diff
changeset
|
139 NOTE: If you had to put if()@{ .. @} over a large (> 5 lines) chunk of code, |
c3501315b4d0
update >5 line reindention rule to what is in ffmpeg
michael
parents:
22591
diff
changeset
|
140 then either do NOT change the indentation of the inner part within (don't |
c3501315b4d0
update >5 line reindention rule to what is in ffmpeg
michael
parents:
22591
diff
changeset
|
141 move it to the right)! or do so in a separate commit |
2200 | 142 |
18841 | 143 |
22368 | 144 Commit log message |
145 Always fill out the commit log message. Describe in a few lines what you | |
13288 | 146 changed and why. You can refer to mailing list postings if you fix a |
147 particular bug. Comments such as "fixed!" or "Changed it." are unacceptable. | |
2200 | 148 |
18841 | 149 |
22368 | 150 Applying patches |
151 If you apply a patch by someone else, include the name and email address in | |
18660 | 152 the log message. Since the mplayer-cvslog mailing list is publicly |
13288 | 153 archived you should add some spam protection to the email address. Send an |
154 answer to mplayer-dev-eng (or wherever you got the patch from) saying that | |
17054 | 155 you applied the patch. If the patch contains a documentation change, commit |
156 that as well; do not leave it to the documentation maintainers. | |
2200 | 157 |
18841 | 158 |
22368 | 159 messing with other developers code |
160 Do NOT commit to code actively maintained by others without permission. Send | |
13288 | 161 a patch to mplayer-dev-eng instead. |
12107
bc89ddda34b8
Developers should subscribe to mplayer-cvslog, mention mplayer-docs.
diego
parents:
12099
diff
changeset
|
162 |
18841 | 163 |
22368 | 164 Subscribe to svnlog |
165 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
|
166 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
|
167 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
|
168 expect you to react if problems with your code are uncovered. |
12024 | 169 |
18841 | 170 |
22368 | 171 Documentation |
172 Update the documentation if you change behavior or add features. If you are | |
13288 | 173 unsure how best to do this, send a patch to mplayer-docs, the documentation |
174 maintainers will review and commit your stuff. | |
175 | |
18841 | 176 |
22368 | 177 Controversial changes |
178 Always send a patch to the mplayer-dev-eng mailing list before committing | |
20783
dc1a1ff6c7d9
Updated for controversial changes and irc-only decisions
rtogni
parents:
19662
diff
changeset
|
179 if you suspect that the change is going to be controversial. Based on past |
dc1a1ff6c7d9
Updated for controversial changes and irc-only decisions
rtogni
parents:
19662
diff
changeset
|
180 experience, these changes are likely to be controversial: |
dc1a1ff6c7d9
Updated for controversial changes and irc-only decisions
rtogni
parents:
19662
diff
changeset
|
181 - feature removal, even if obsolete |
dc1a1ff6c7d9
Updated for controversial changes and irc-only decisions
rtogni
parents:
19662
diff
changeset
|
182 - changes to "special" output messages (like the "Core dumped ;)" message) |
dc1a1ff6c7d9
Updated for controversial changes and irc-only decisions
rtogni
parents:
19662
diff
changeset
|
183 - verbosity changes from default (info) level |
dc1a1ff6c7d9
Updated for controversial changes and irc-only decisions
rtogni
parents:
19662
diff
changeset
|
184 - changes to "historical" parts of docs and webpages |
dc1a1ff6c7d9
Updated for controversial changes and irc-only decisions
rtogni
parents:
19662
diff
changeset
|
185 - use of internal or external libraries |
22368 | 186 - changes to the internal architecture |
187 - non trivial changes to very fundamental parts of mplayer | |
20783
dc1a1ff6c7d9
Updated for controversial changes and irc-only decisions
rtogni
parents:
19662
diff
changeset
|
188 |
dc1a1ff6c7d9
Updated for controversial changes and irc-only decisions
rtogni
parents:
19662
diff
changeset
|
189 |
22368 | 190 Public discussions |
191 Try to keep important discussions and requests (also) on the | |
20783
dc1a1ff6c7d9
Updated for controversial changes and irc-only decisions
rtogni
parents:
19662
diff
changeset
|
192 mplayer-dev-eng mailing list, so that all developers can benefit from them. |
dc1a1ff6c7d9
Updated for controversial changes and irc-only decisions
rtogni
parents:
19662
diff
changeset
|
193 IRC is good for quick discussions, but nobody is there 24/7. |
22368 | 194 also subscribe to the public developer mailing list |
20783
dc1a1ff6c7d9
Updated for controversial changes and irc-only decisions
rtogni
parents:
19662
diff
changeset
|
195 |
dc1a1ff6c7d9
Updated for controversial changes and irc-only decisions
rtogni
parents:
19662
diff
changeset
|
196 |
22590
e03a45f3a360
cosmetic (move warning point after the existing policy points instead of the middle)
michael
parents:
22532
diff
changeset
|
197 Compiler Warning fixes |
e03a45f3a360
cosmetic (move warning point after the existing policy points instead of the middle)
michael
parents:
22532
diff
changeset
|
198 Do not change code to hide warnings without ensuring that the underlaying |
e03a45f3a360
cosmetic (move warning point after the existing policy points instead of the middle)
michael
parents:
22532
diff
changeset
|
199 logic is correct and thus the warning was inappropriate |
e03a45f3a360
cosmetic (move warning point after the existing policy points instead of the middle)
michael
parents:
22532
diff
changeset
|
200 |
e03a45f3a360
cosmetic (move warning point after the existing policy points instead of the middle)
michael
parents:
22532
diff
changeset
|
201 |
22368 | 202 Patches |
203 read and follow patches.txt when sending patches for mplayer | |
7904
98168d30f67d
Spellchecked, reworded, reformatted, small additions and corrections.
diego
parents:
5415
diff
changeset
|
204 |
3258 | 205 |
22368 | 206 Insults |
207 Do not insult other people in relation to mplayer on any public mailing | |
208 list, that is calling code from someone else a pile of broken shit is | |
209 perfectly fine but calling the developer herself a retarded f*cking moron | |
210 is not acceptable | |
18828 | 211 |
18841 | 212 |
22368 | 213 Forking |
22382 | 214 People disagreeing with the developers or leaders may fork the project, |
215 the leaders MUST in that case provide a svn dump with all history if | |
22368 | 216 the person forking wants one |
18828 | 217 |
18841 | 218 |
22368 | 219 Communicating passwords |
220 Developers who have provided a public gpg key shall only receive | |
221 passwords or other sensitive information related to mplayer encrypted | |
222 with their gpg key | |
18828 | 223 |
18841 | 224 |
22368 | 225 V. Votes |
226 -------- | |
227 Its inevitable that some things will be decided by voting, votes in the past | |
228 have due to total lack of rules been problematic for example as many people | |
229 rather wrote long texts and voted based on some condition instead of saying | |
230 a clear yes or no, still its important that people can vote based on a | |
231 condition | |
22382 | 232 The result of a vote is binding for all developers and leaders, though of |
233 course they can leave the project and thus cease to be a developer or leader | |
22368 | 234 any time |
18828 | 235 |
22368 | 236 Vs. Starting a vote |
237 Any single developer can start a vote, to do so she has to send a mail to the | |
238 public developer mailing list of the project with a subject containing [VOTE] | |
239 and a clear and concise description, a longer descrition can be in the body | |
240 of the mail | |
241 | |
242 Vp. Proposing an option (point on the ballot, better term?) | |
22373 | 243 Any single developer can propose an option up to 7 days after a vote has |
22368 | 244 been started, to do so she has to reply to the original vote mail on the |
22373 | 245 public developer mailing list and clearly, concise and unmistakably describe |
22368 | 246 the option and place [VOTE-OPTION] instead of [VOTE] in the subject |
247 in addition to proposed options, there always exists the default option | |
248 of doing nothing | |
249 options can be conditional on anything which at the end of the vote can | |
22373 | 250 be clearly and unmistakably be answered with true or false |
18828 | 251 |
22368 | 252 Vv. Voting |
22373 | 253 Any developer can cast a vote up to 10 days days after a vote has been |
22368 | 254 started, to do so she has to reply to the original vote mail on the |
255 public developer mailing list and rate options each with an integer | |
256 unrated options shall be counted equal to the default option | |
22382 | 257 Any leader can cast a veto against any option except the default up to 10 days |
22368 | 258 days after a vote has been started, to do so she has to reply to the original |
259 vote mail on the public developer mailing list and replace | |
260 [VOTE] by [VOTE-VETO] | |
22382 | 261 Developers and leaders who use gpg/pgp MUST sign their votes and vetoes |
18828 | 262 |
22368 | 263 Vc. Counting votes |
22373 | 264 The person starting the vote has to count the votes and vetoes and publish |
22368 | 265 the result on the public developer mailing list as reply to the original vote |
266 with [VOTE-RESULTS] instead of [VOTE] in the subject | |
22386
6c9a391ca7cb
clarify quorum and majority requirements in respect to debians voting system
michael
parents:
22385
diff
changeset
|
267 Vcv. Counting vetoes |
6c9a391ca7cb
clarify quorum and majority requirements in respect to debians voting system
michael
parents:
22385
diff
changeset
|
268 if the majority of leaders that is yes >= no && yes>0 cast a veto against an |
6c9a391ca7cb
clarify quorum and majority requirements in respect to debians voting system
michael
parents:
22385
diff
changeset
|
269 option then it has a required supermajority of 2:1 otherwise it has a |
6c9a391ca7cb
clarify quorum and majority requirements in respect to debians voting system
michael
parents:
22385
diff
changeset
|
270 required supermajority of 0:1 and in either case no quorum requirement |
22368 | 271 Vcc. the votes shall be counted by using the Condorcet/Clone Proof SSD |
22385
867f18d80b31
url with a good description of how to determine the winner from the votes
michael
parents:
22382
diff
changeset
|
272 Voting Method described in http://www.debian.org/devel/constitution A.6 |
22368 | 273 |
22386
6c9a391ca7cb
clarify quorum and majority requirements in respect to debians voting system
michael
parents:
22385
diff
changeset
|
274 Reasoning behind avoiding of a quorum and majority requirement except in |
6c9a391ca7cb
clarify quorum and majority requirements in respect to debians voting system
michael
parents:
22385
diff
changeset
|
275 the case of vetoes |
6c9a391ca7cb
clarify quorum and majority requirements in respect to debians voting system
michael
parents:
22385
diff
changeset
|
276 short awnser its stupid and has catastrophical failure modes |
6c9a391ca7cb
clarify quorum and majority requirements in respect to debians voting system
michael
parents:
22385
diff
changeset
|
277 example of one such failure mode, lets assume a 1:1 majority requirement |
6c9a391ca7cb
clarify quorum and majority requirements in respect to debians voting system
michael
parents:
22385
diff
changeset
|
278 as debian uses by default, there are 101 developers who vote, there are |
6c9a391ca7cb
clarify quorum and majority requirements in respect to debians voting system
michael
parents:
22385
diff
changeset
|
279 3 options A,B and D the default (doing nothing / further discussions) |
6c9a391ca7cb
clarify quorum and majority requirements in respect to debians voting system
michael
parents:
22385
diff
changeset
|
280 50 developers prefer A over B and B over discussions (A>B>D) |
6c9a391ca7cb
clarify quorum and majority requirements in respect to debians voting system
michael
parents:
22385
diff
changeset
|
281 50 developers prefer discussions over A and A over B (D>A>B) |
6c9a391ca7cb
clarify quorum and majority requirements in respect to debians voting system
michael
parents:
22385
diff
changeset
|
282 1 developer prefers B over discussions and discussions over A (B>D>A) |
6c9a391ca7cb
clarify quorum and majority requirements in respect to debians voting system
michael
parents:
22385
diff
changeset
|
283 in this case A is approved by 50 of 101 developers and is droped due to |
6c9a391ca7cb
clarify quorum and majority requirements in respect to debians voting system
michael
parents:
22385
diff
changeset
|
284 the lack of majority, B is approved by 51 of 101 developers and is not |
6c9a391ca7cb
clarify quorum and majority requirements in respect to debians voting system
michael
parents:
22385
diff
changeset
|
285 furthermore B wins even though 100 of 101 developers prefer A over B |
6c9a391ca7cb
clarify quorum and majority requirements in respect to debians voting system
michael
parents:
22385
diff
changeset
|
286 |
6c9a391ca7cb
clarify quorum and majority requirements in respect to debians voting system
michael
parents:
22385
diff
changeset
|
287 |
22382 | 288 S. Changes to developer and Leader status |
22368 | 289 ---------------------------------------- |
22382 | 290 The majority of leaders, that is yes>no can give and take away |
291 developer and leader status to people | |
292 furthermore any developer or leader can step back and thus loose | |
293 his leader and or developer status | |
294 People disagreeing with the leaders are free to fork the project | |
22368 | 295 new developers should be asked for real name, public gpg key, phone |
296 number and email addresses, none of this is mandatory though, it is asked | |
297 so as to be able to contact the developer if the need arises and one | |
298 contact method fails | |
18828 | 299 |
18841 | 300 |
22368 | 301 O. Violations |
302 ------------- | |
22382 | 303 Any leader can after at least one leader has warned another developer |
22373 | 304 due to breaking policy, suspend his account if he repeats the violation |
22368 | 305 Ow. A policy violation warning MUST be CCed to the developer who violated |
306 the policy | |
18828 | 307 |
18841 | 308 |
22530 | 309 We think our rules are not too hard. If you have comments, contact us. |