Mercurial > mplayer.hg
annotate DOCS/tech/patches.txt @ 33263:5f527a9a9521
Add an exit function.
This function will allow performing clean-up operations.
(MPlayer calls guiDone() before exiting, but only if the GUI has been
initialized, i.e. if guiInit() has been called successfully. Any
exit_player()/exit_player_with_rc() after GUI's cfg_read() until
guiInit(), or any exit_player() during guiInit() itself will end the GUI
without calling guiDone(). This exit function will at least handle
abortions during guiInit() itself. It will be called twice in case of an
guiExit() after GUI initialization - first directly, next by guiDone()
via MPlayer's exit_player_with_rc().)
author | ib |
---|---|
date | Tue, 03 May 2011 12:19:22 +0000 |
parents | 81c9be1beeec |
children |
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 |
18646 | 15 1. Always make patches for Subversion HEAD. The README describes how to check |
16 out Subversion and daily snapshots are available from our download page. | |
17 We do not accept patches for releases or outdated Subversion revisions. | |
2121 | 18 |
18646 | 19 2. Make unified diffs ('svn diff' or 'diff -Naur'). Unified diffs can be |
12602
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. |
18372 | 21 Besides, unified diffs are more readable and thus easier to review. |
18361 | 22 |
23 3. Create the diff from the root of the MPlayer source tree, this makes the | |
18372 | 24 diff easier to apply as it saves the step of searching for and changing |
25 to the correct directory. | |
2121 | 26 |
18360 | 27 4. Test the functionality of your patch. We'll *refuse* it if it breaks |
12602
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
28 something, even if it extends other features! |
2121 | 29 |
18360 | 30 5. Read your patch. We'll *refuse* it if it changes indentation of the |
12900
a5df08927328
Wording/spelling suggestions by the Wanderer, merged sections about when to
diego
parents:
12898
diff
changeset
|
31 code or if it does tab/space conversion or other cosmetic changes! |
2121 | 32 |
12898
2054ffe13177
Explain how to handle big patches and why uploading patches is bad.
diego
parents:
12812
diff
changeset
|
33 NOTE: If you already wrote some code and did cosmetic changes, you can |
12602
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
34 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
|
35 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
|
36 any remaining cosmetics! |
24543 | 37 To use these options directly with svn, use this command: |
38 svn diff --diff-cmd diff -x -uwbBE | |
12419
3a6e4fff88e3
Hint at diff options useful for avoiding cosmetic changes, patch by Reimar.
diego
parents:
12251
diff
changeset
|
39 |
18360 | 40 6. Comment parts that really need it (tricky side-effects etc). |
12701
4e0acc8d3622
Explain that commenting string operations is important.
diego
parents:
12602
diff
changeset
|
41 Always document string operations! Comment on what you are doing |
4e0acc8d3622
Explain that commenting string operations is important.
diego
parents:
12602
diff
changeset
|
42 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
|
43 code if needed. Commenting trivial code not required. |
4e0acc8d3622
Explain that commenting string operations is important.
diego
parents:
12602
diff
changeset
|
44 Comments must be English! |
8556 | 45 |
18360 | 46 7. If you implement new features, add or change command line switches or |
12602
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
47 modify the behavior of existing features, please do not forget to also |
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
48 update the documentation. The documentation maintainers will assist you |
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
49 in doing this. Updating the English documentation is enough. If you |
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
50 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
|
51 translations as well. |
12106 | 52 |
18360 | 53 8. If you make independent changes, try to send them as separate patches |
13414
ea01d0554a6e
split patches up as far as sensibly possible, but no further.
diego
parents:
13258
diff
changeset
|
54 in separate mails. Likewise, if your patch is very big, try splitting |
ea01d0554a6e
split patches up as far as sensibly possible, but no further.
diego
parents:
13258
diff
changeset
|
55 it into several self-contained pieces. Each part can then be reviewed |
ea01d0554a6e
split patches up as far as sensibly possible, but no further.
diego
parents:
13258
diff
changeset
|
56 and committed separately. Logical units should stay together, though, |
21472 | 57 i.e. do not send a patch for every file or directory you change. |
12898
2054ffe13177
Explain how to handle big patches and why uploading patches is bad.
diego
parents:
12812
diff
changeset
|
58 |
30944 | 59 9. Send your patch to the mplayer-dev-eng mailing list as attachment with |
60 the subject line: | |
12812
d63e770baf9f
Patches should be created from the root of the source directory, explanation
diego
parents:
12701
diff
changeset
|
61 '[PATCH] very short description of the patch'. |
12602
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
62 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
|
63 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
|
64 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
|
65 for unapplied patches, so please use it. |
14898
57d00d7a9182
Patches should not be sent as replies to unrelated threads.
diego
parents:
13414
diff
changeset
|
66 Do not send your patch as a reply to some other unrelated mail, compose |
57d00d7a9182
Patches should not be sent as replies to unrelated threads.
diego
parents:
13414
diff
changeset
|
67 a new message, otherwise it will probably get overlooked. |
32514
81c9be1beeec
Remove outdated reference to 80kB patch size limit; the limit no longer exists.
diego
parents:
30944
diff
changeset
|
68 Do not compress your patch unless it is very large or if you know |
12812
d63e770baf9f
Patches should be created from the root of the source directory, explanation
diego
parents:
12701
diff
changeset
|
69 that your mailer messes up (reformats) text attachments. It only makes |
13156
ccce2d564161
Patches should be gzip or bzip2 compressed if necessary.
diego
parents:
12900
diff
changeset
|
70 handling the patch more difficult. If you have to compress your patch, |
13258
7903766338f7
some new patch policy: compression, mail threading, printf vs mp_msg
diego
parents:
13156
diff
changeset
|
71 use either bzip2, gzip or zip to compress it, not a different format. |
12602
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
72 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
|
73 non-subscribers after spam problems and because patches get reviewed by |
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
74 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
|
75 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
|
76 Don't worry, mplayer-dev-eng is not high traffic and you can subscribe |
12898
2054ffe13177
Explain how to handle big patches and why uploading patches is bad.
diego
parents:
12812
diff
changeset
|
77 but unset the "Mail delivery" option so that you can post without getting |
2054ffe13177
Explain how to handle big patches and why uploading patches is bad.
diego
parents:
12812
diff
changeset
|
78 any mails. |
13258
7903766338f7
some new patch policy: compression, mail threading, printf vs mp_msg
diego
parents:
13156
diff
changeset
|
79 Do not upload the patch to a web or FTP site, send it directly to the |
7903766338f7
some new patch policy: compression, mail threading, printf vs mp_msg
diego
parents:
13156
diff
changeset
|
80 mailing list. The fewer steps it takes us to get at the patch the higher |
7903766338f7
some new patch policy: compression, mail threading, printf vs mp_msg
diego
parents:
13156
diff
changeset
|
81 the likelihood for it to get reviewed and applied. If your patch is so |
7903766338f7
some new patch policy: compression, mail threading, printf vs mp_msg
diego
parents:
13156
diff
changeset
|
82 big you cannot send it by mail, try splitting it into smaller pieces. |
2121 | 83 |
18360 | 84 10. Give us a few days to react. We try to review patches as fast as possible, |
12900
a5df08927328
Wording/spelling suggestions by the Wanderer, merged sections about when to
diego
parents:
12898
diff
changeset
|
85 but unfortunately we are constantly overloaded with work, be it MPlayer- |
12602
0d9dec871b83
cosmetic reformatting (preparation for upcoming changes)
diego
parents:
12419
diff
changeset
|
86 related or from our day to day lives. If your patch seems to be ignored, |
13258
7903766338f7
some new patch policy: compression, mail threading, printf vs mp_msg
diego
parents:
13156
diff
changeset
|
87 send a reminder asking for opinions as a reply to the original patch and |
7903766338f7
some new patch policy: compression, mail threading, printf vs mp_msg
diego
parents:
13156
diff
changeset
|
88 mention that you got ignored. We are interested in your work and will |
7903766338f7
some new patch policy: compression, mail threading, printf vs mp_msg
diego
parents:
13156
diff
changeset
|
89 eventually either accept it or reject it with an explanation of what we |
7903766338f7
some new patch policy: compression, mail threading, printf vs mp_msg
diego
parents:
13156
diff
changeset
|
90 disliked about your patch. We will often ask you to make changes to your |
7903766338f7
some new patch policy: compression, mail threading, printf vs mp_msg
diego
parents:
13156
diff
changeset
|
91 patch to make it acceptable. Implement them if you want to see your patch |
7903766338f7
some new patch policy: compression, mail threading, printf vs mp_msg
diego
parents:
13156
diff
changeset
|
92 applied and send the update to the mailing list. Remember that updates and |
7903766338f7
some new patch policy: compression, mail threading, printf vs mp_msg
diego
parents:
13156
diff
changeset
|
93 reminders must be sent as replies to the original patch to preserve proper |
7903766338f7
some new patch policy: compression, mail threading, printf vs mp_msg
diego
parents:
13156
diff
changeset
|
94 mail threading. |
8432 | 95 |
18646 | 96 11. Do not immediately ask for Subversion write access. If you have contributed |
97 one or more nice, acceptable patches and they need maintaining or you want | |
98 to be an MPlayer developer, you'll get Subversion write access. | |
11283 | 99 |
18360 | 100 12. 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
|
101 |
18360 | 102 13. If you make a nontrivial contribution and wish to be mentioned in the |
11459
74e69aef2406
Contributors should also patch AUTHORS if they wish to appear there.
diego
parents:
11283
diff
changeset
|
103 AUTHORS file, include that in your patch. |
12106 | 104 |
18360 | 105 14. Do not use printf for console output, use our own mp_msg functions instead. |
13258
7903766338f7
some new patch policy: compression, mail threading, printf vs mp_msg
diego
parents:
13156
diff
changeset
|
106 For the output to be translated (which includes all messages of level |
7903766338f7
some new patch policy: compression, mail threading, printf vs mp_msg
diego
parents:
13156
diff
changeset
|
107 MSGL_HINT and below), put the strings in help/help_mp-en.h. If you change |
7903766338f7
some new patch policy: compression, mail threading, printf vs mp_msg
diego
parents:
13156
diff
changeset
|
108 strings, remove the occurrences of these strings from the translations. |
7903766338f7
some new patch policy: compression, mail threading, printf vs mp_msg
diego
parents:
13156
diff
changeset
|
109 There may be (compilation) trouble if outdated translations remain in place |
7903766338f7
some new patch policy: compression, mail threading, printf vs mp_msg
diego
parents:
13156
diff
changeset
|
110 and translators will pick up changes more easily if they see a new message |
7903766338f7
some new patch policy: compression, mail threading, printf vs mp_msg
diego
parents:
13156
diff
changeset
|
111 that has to be translated. |
7903766338f7
some new patch policy: compression, mail threading, printf vs mp_msg
diego
parents:
13156
diff
changeset
|
112 |
18372 | 113 15. If you send a modified or updated version of your patch, resend the |
114 complete patch. It is very time-consuming and error-prone to piece | |
115 together patches that are distributed over several mails. | |
18359 | 116 Please always resend patches as replies to the original mail to keep |
117 the thread with the discussion together. | |
118 | |
2121 | 119 Thank you! |