whitespace cosmetics: Remove all trailing whitespace.
[mplayer.git] / DOCS / tech / new_policy_proposal.txt
1 New Policy Draft
2 Version 20070301
3
4 Intro:
5 ------
6 This document is an attempt to write a new policy as the old is fairly
7 confusing and easy to misunderstand, its intention is not really to
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
12
13 Author:
14 -------
15 Michael Niedermayer
16 the authors of the old policy as I liberally copy and pasted from it
17
18 TODO:
19 add more explanations, justifications and examples
20 how to become/loose maintainer status
21 review patches.txt
22 security/exploit rules
23 ------------------------
24
25
26 1. Definitions
27 --------------
28 * MPlayer developer, generally referred to simply as developer in this document
29   is any person who has a open (not cracked, not suspended) svn write account
30 * MPlayer leader, generally referred to simply as leader in this document, every
31   leader is also a developer
32 * CAN/MUST/SHOULD descriptions ...
33 * public developer mailing list (mplayer-dev-eng at mplayerhq in hungary)
34
35
36 C. Code and SVN Rules
37 -----------------------------
38 Renaming/moving/copying files or contents of files
39   Do not move, rename or copy files of which you are not the maintainer without
40   discussing it on the public developer mailinglist first!
41
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.
45
46   To split a file, use 'svn copy' and remove the unneeded lines from each file.
47
48   Don't do a lot of cut'n'paste from one file to another without a very good
49   reason and discuss it on the mplayer-dev-eng mailing list first. It will make
50   those changes hard to trace.
51
52   Such actions are useless and treated as cosmetics in 99% of cases,
53   so try to avoid them.
54
55 Reverting broken commits
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
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
77   changes then it is better if it is not part of the visible history as it
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
80   should of course be committed again after the reversal but separately, so one
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
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
88   the actual change does not clutter the immediately visible history and
89   svn annotate.
90   If you are even just slightly uncertain how to revert something then ask on
91   the mplayer-dev-eng mailing list.
92
93 Broken code
94    You must not commit code which breaks MPlayer! (Meaning unfinished but
95    enabled code which breaks compilation or compiles but does not work.)
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.
99
100 Testing code
101    You don't have to over-test things. If it works for you, and you think it
102    should work for others, too, then commit. If your code has problems
103    (portability, exploits compiler bugs, unusual environment etc) they will be
104    reported and eventually fixed.
105
106 Splitting changes
107    Do not commit unrelated changes together, split them into self-contained
108    pieces. Also dont forget that if part B depends on part A but A doesnt
109    depend on B, then A can and should be commited first and seperately from B.
110    Keeping changes well split into self contained parts makes reviewing and
111    understanding them on svn log at the time of commit and later when
112    debugging a bug much easier.
113    Also if you have doubt about spliting or not spliting, dont hesitate to
114    ask/disscuss it on the developer mailing list.
115
116 4. Do not change behavior of the program (renaming options etc) or
117    remove functionality from the code without approval in a discussion on
118    the mplayer-dev-eng mailing list.
119
120
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
129
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
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.
138
139    NOTE: If you had to put if()@{ .. @} over a large (> 5 lines) chunk of code,
140    then either do NOT change the indentation of the inner part within (don't
141    move it to the right)! or do so in a separate commit
142
143
144 Commit log message
145    Always fill out the commit log message. Describe in a few lines what you
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.
148
149
150 Applying patches
151    If you apply a patch by someone else, include the name and email address in
152    the log message. Since the mplayer-cvslog mailing list is publicly
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
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.
157
158
159 messing with other developers code
160    Do NOT commit to code actively maintained by others without permission. Send
161    a patch to mplayer-dev-eng instead.
162
163
164 Subscribe to svnlog
165     Subscribe to the mplayer-cvslog mailing list. The diffs of all commits
166     are sent there and reviewed by all the other developers. Bugs and possible
167     improvements or general questions regarding commits are discussed there. We
168     expect you to react if problems with your code are uncovered.
169
170
171 Documentation
172     Update the documentation if you change behavior or add features. If you are
173     unsure how best to do this, send a patch to mplayer-docs, the documentation
174     maintainers will review and commit your stuff.
175
176
177 Controversial changes
178     Always send a patch to the mplayer-dev-eng mailing list before committing
179     if you suspect that the change is going to be controversial. Based on past
180     experience, these changes are likely to be controversial:
181      - feature removal, even if obsolete
182      - changes to "special" output messages (like the "Core dumped ;)" message)
183      - verbosity changes from default (info) level
184      - changes to "historical" parts of docs and webpages
185      - use of internal or external libraries
186      - changes to the internal architecture
187      - non trivial changes to very fundamental parts of mplayer
188
189
190 Public discussions
191     Try to keep important discussions and requests (also) on the
192     mplayer-dev-eng mailing list, so that all developers can benefit from them.
193     IRC is good for quick discussions, but nobody is there 24/7.
194     also subscribe to the public developer mailing list
195
196
197 Compiler Warning fixes
198    Do not change code to hide warnings without ensuring that the underlaying
199    logic is correct and thus the warning was inappropriate
200
201
202 Patches
203     read and follow patches.txt when sending patches for mplayer
204
205
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
211
212
213 Forking
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
216     the person forking wants one
217
218
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 or in another secure way
223
224
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
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
234 any time
235
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?)
243 Any single developer can propose an option up to 7 days after a vote has
244 been started, to do so she has to reply to the original vote mail on the
245 public developer mailing list and clearly, concise and unmistakably describe
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
250 be clearly and unmistakably be answered with true or false
251
252 Vv. Voting
253 Any developer can cast a vote up to 10 days days after a vote has been
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
257 Any leader can cast a veto against any option except the default up to 10 days
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]
261 Developers and leaders who use gpg/pgp MUST sign their votes and vetoes
262
263 Vc. Counting votes
264 The person starting the vote has to count the votes and vetoes and publish
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
267 Vcv. Counting vetoes
268 if the majority of leaders that is yes >= no && yes>0 cast a veto against an
269 option then it has a required supermajority of 2:1 otherwise it has a
270 required supermajority of 0:1 and in either case no quorum requirement
271 Vcc. the votes shall be counted by using the Condorcet/Clone Proof SSD
272 Voting Method described in http://www.debian.org/devel/constitution A.6
273
274 Reasoning behind avoiding of a quorum and majority requirement except in
275 the case of vetoes
276 short awnser its stupid and has catastrophical failure modes
277 example of one such failure mode, lets assume a 1:1 majority requirement
278 as debian uses by default, there are 101 developers who vote, there are
279 3 options A,B and D the default (doing nothing / further discussions)
280 50 developers prefer A over B and B over discussions (A>B>D)
281 50 developers prefer discussions over A and A over B (D>A>B)
282 1 developer prefers B over discussions and discussions over A (B>D>A)
283 in this case A is approved by 50 of 101 developers and is droped due to
284 the lack of majority, B is approved by 51 of 101 developers and is not
285 furthermore B wins even though 100 of 101 developers prefer A over B
286
287
288 S. Changes to developer and Leader status
289 ----------------------------------------
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
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
299
300
301 O. Violations
302 -------------
303 Any leader can after at least one leader has warned another developer
304 due to breaking policy, suspend his account if he repeats the violation
305 Ow. A policy violation warning MUST be CCed to the developer who violated
306 the policy
307
308
309 We think our rules are not too hard. If you have comments, contact us.