Mercurial > mplayer.hg
annotate DOCS/tech/patches.txt @ 12812:d63e770baf9f
Patches should be created from the root of the source directory, explanation
improved.
author | diego |
---|---|
date | Wed, 14 Jul 2004 01:11:14 +0000 |
parents | 4e0acc8d3622 |
children | 2054ffe13177 |
rev | line source |
---|---|
2121 | 1 Sending patches: |
2 ~~~~~~~~~~~~~~~~ | |
3 | |
7645
534b9b6f6557
Some further explanations, dev-eng is now subscribers only.
diego
parents:
7153
diff
changeset
|
4 Note: We know our rules place a burden on you, but rest assured that |
534b9b6f6557
Some further explanations, dev-eng is now subscribers only.
diego
parents:
7153
diff
changeset
|
5 maintaining a big and complex software project is even harder, so please |
534b9b6f6557
Some further explanations, dev-eng is now subscribers only.
diego
parents:
7153
diff
changeset
|
6 accept our rules. We cannot afford to spend our time fixing buggy, broken or |
12218 | 7 outdated patches. The closer you follow our rules the higher is the probability |
8 that your patch will be included. | |
7645
534b9b6f6557
Some further explanations, dev-eng is now subscribers only.
diego
parents:
7153
diff
changeset
|
9 |
12602
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
10 0. Do not send complete files. These need to be diffed by hand to see the |
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
11 changes, which makes reviews harder and less likely to occur. Besides as |
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
12 soon as one of the files changes, your version becomes harder to apply, |
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
13 thus reducing its chances of being accepted. |
11191 | 14 |
12602
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
15 1. Always make patches for the CVS version. The README describes how to check |
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
16 out CVS and daily CVS snapshots are available from our download page. |
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
17 We do not accept patches for releases or outdated CVS versions. |
2121 | 18 |
12602
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
19 2. Make unified diffs ('diff -Naur' or 'cvs diff -u'). Unified diffs can be |
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
20 applied easily with 'patch'. This is much harder with other diff types. |
12812
d63e770baf9f
Patches should be created from the root of the source directory, explanation
diego
parents:
12701
diff
changeset
|
21 Create the diff from the root of the MPlayer source tree, this makes the |
d63e770baf9f
Patches should be created from the root of the source directory, explanation
diego
parents:
12701
diff
changeset
|
22 diff easier to apply as it saves the step of changing to the correct |
d63e770baf9f
Patches should be created from the root of the source directory, explanation
diego
parents:
12701
diff
changeset
|
23 directory. |
2121 | 24 |
12602
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
25 3. Test the functionality of your patch. We'll *refuse* it if it breaks |
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
26 something, even if it extends other features! |
2121 | 27 |
12602
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
28 4. Read your patch. We'll *refuse* it if it changes indentation of the |
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
29 code or if it does tab/space conversion or other cosmetical changes! |
2121 | 30 |
12602
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
31 NOTE: If you alread wrote some code and did cosmetic changes, you can |
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
32 use 'diff -uwbBE' to help you remove them. Don't forget to check the |
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
33 patch to make sure diff didn't ignore some important change and remove |
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
34 any remaining cosmetics! |
12419
3a6e4fff88e3
Hint at diff options useful for avoiding cosmetic changes, patch by Reimar.
diego
parents:
12251
diff
changeset
|
35 |
12602
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
36 5. Comment parts that really need it (tricky side-effects etc). |
12701
4e0acc8d3622
Explain that commenting string operations is important.
diego
parents:
12602
diff
changeset
|
37 Always document string operations! Comment on what you are doing |
4e0acc8d3622
Explain that commenting string operations is important.
diego
parents:
12602
diff
changeset
|
38 and why it is safe. This makes it easy to review and change your |
4e0acc8d3622
Explain that commenting string operations is important.
diego
parents:
12602
diff
changeset
|
39 code if needed. Commenting trivial code not required. |
4e0acc8d3622
Explain that commenting string operations is important.
diego
parents:
12602
diff
changeset
|
40 Comments must be English! |
8556 | 41 |
12602
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
42 6. If you implement new features, add or change command line switches or |
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
43 modify the behavior of existing features, please do not forget to also |
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
44 update the documentation. The documentation maintainers will assist you |
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
45 in doing this. Updating the English documentation is enough. If you |
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
46 speak several languages you are of course welcome to update some of the |
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
47 translations as well. |
12106 | 48 |
12602
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
49 7. Send your patch to the mplayer-dev-eng mailing list as a base64-encoded |
12812
d63e770baf9f
Patches should be created from the root of the source directory, explanation
diego
parents:
12701
diff
changeset
|
50 attachment with the subject line: |
d63e770baf9f
Patches should be created from the root of the source directory, explanation
diego
parents:
12701
diff
changeset
|
51 '[PATCH] very short description of the patch'. |
12602
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
52 In the mail, describe in a few sentences what you change and why. |
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
53 The subject line is very important if you do not want your patch to get |
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
54 lost in the noise. We need the uppercase [PATCH] to be able to search |
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
55 for unapplied patches, so please use it. |
12812
d63e770baf9f
Patches should be created from the root of the source directory, explanation
diego
parents:
12701
diff
changeset
|
56 Do not compress your patch unless it is larger than 80k or if you know |
d63e770baf9f
Patches should be created from the root of the source directory, explanation
diego
parents:
12701
diff
changeset
|
57 that your mailer messes up (reformats) text attachments. It only makes |
d63e770baf9f
Patches should be created from the root of the source directory, explanation
diego
parents:
12701
diff
changeset
|
58 handling the patch more difficult. |
12602
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
59 You have to subscribe to mplayer-dev-eng since we blocked postings from |
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
60 non-subscribers after spam problems and because patches get reviewed by |
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
61 the developers on the list. We want you to be available for discussing |
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
62 your code, you might be asked to make modifications before we accept it. |
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
63 Don't worry, mplayer-dev-eng is not high traffic and you can subscribe |
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
64 with the nomail option if you do not wish to receive all the mails. |
2121 | 65 |
12602
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
66 8. Give us a few days to react. We try to review patches as fast as possible, |
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
67 but unfortunately we are constantly overloaded with work, be it MPlayer |
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
68 related or from our day to day lives. If your patch seems to be ignored, |
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
69 please resend it and mention that you got ignored. We are interested in |
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
70 your work and will eventually either accept it or reject it with an |
12812
d63e770baf9f
Patches should be created from the root of the source directory, explanation
diego
parents:
12701
diff
changeset
|
71 explanation of what we disliked about your patch. |
8432 | 72 |
12602
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
73 9. Do not immediately ask for CVS write access. If you contributed one or |
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
74 more nice, acceptable patches and they need maintaining or you want to |
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
75 be an MPlayer developer, you'll get CVS write access. |
11283 | 76 |
77 10. For consistency reasons all option names must use '-' instead of '_'. | |
11459
74e69aef2406
Contributors should also patch AUTHORS if they wish to appear there.
diego
parents:
11283
diff
changeset
|
78 |
74e69aef2406
Contributors should also patch AUTHORS if they wish to appear there.
diego
parents:
11283
diff
changeset
|
79 11. If you made a nontrivial contribution and wish to be mentioned in the |
74e69aef2406
Contributors should also patch AUTHORS if they wish to appear there.
diego
parents:
11283
diff
changeset
|
80 AUTHORS file, include that in your patch. |
12106 | 81 |
12812
d63e770baf9f
Patches should be created from the root of the source directory, explanation
diego
parents:
12701
diff
changeset
|
82 12. If you made independent changes, try to send them as separate patches. |
12218 | 83 |
2121 | 84 Thank you! |