annotate DOCS/tech/patches.txt @ 14561:a226d301eec1

Handle missing palettes in the info part of VobSubs in Matroska files correctly by giving mplayer a NULL pointer. This way it will use a default palette instead of black only. Patch by Csillag Kristof (fenwick () freemail ! hu)
author mosu
date Fri, 21 Jan 2005 18:25:44 +0000
parents ea01d0554a6e
children 57d00d7a9182
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
2121
95b8a1e7962d sending patches
arpi
parents:
diff changeset
1 Sending patches:
95b8a1e7962d sending patches
arpi
parents:
diff changeset
2 ~~~~~~~~~~~~~~~~
95b8a1e7962d sending patches
arpi
parents:
diff changeset
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
52de6cbd0842 Patches should not be compressed.
diego
parents: 12106
diff changeset
7 outdated patches. The closer you follow our rules the higher is the probability
52de6cbd0842 Patches should not be compressed.
diego
parents: 12106
diff changeset
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
ed5969812ff3 Explain why sending complete files is a bad idea.
diego
parents: 10943
diff changeset
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
95b8a1e7962d sending patches
arpi
parents:
diff changeset
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
95b8a1e7962d sending patches
arpi
parents:
diff changeset
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
95b8a1e7962d sending patches
arpi
parents:
diff changeset
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
12900
a5df08927328 Wording/spelling suggestions by the Wanderer, merged sections about when to
diego
parents: 12898
diff changeset
29 code or if it does tab/space conversion or other cosmetic changes!
2121
95b8a1e7962d sending patches
arpi
parents:
diff changeset
30
12898
2054ffe13177 Explain how to handle big patches and why uploading patches is bad.
diego
parents: 12812
diff changeset
31 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
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
ecff1745d189 Document things from the start.
diego
parents: 8432
diff changeset
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
a79d9b3a83fd cosmetics
diego
parents: 11459
diff changeset
48
13414
ea01d0554a6e split patches up as far as sensibly possible, but no further.
diego
parents: 13258
diff changeset
49 7. If you make independent changes, try to send them as separate patches
ea01d0554a6e split patches up as far as sensibly possible, but no further.
diego
parents: 13258
diff changeset
50 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
51 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
52 and committed separately. Logical units should stay together, though,
ea01d0554a6e split patches up as far as sensibly possible, but no further.
diego
parents: 13258
diff changeset
53 e.g. do not send a patch for every file you change.
12898
2054ffe13177 Explain how to handle big patches and why uploading patches is bad.
diego
parents: 12812
diff changeset
54
2054ffe13177 Explain how to handle big patches and why uploading patches is bad.
diego
parents: 12812
diff changeset
55 8. 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
56 attachment with the subject line:
d63e770baf9f Patches should be created from the root of the source directory, explanation
diego
parents: 12701
diff changeset
57 '[PATCH] very short description of the patch'.
12602
0d9dec871b83 cosmetic reformatting (preparation for upcoming changes)
diego
parents: 12419
diff changeset
58 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
59 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
60 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
61 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
62 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
63 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
64 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
65 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
66 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
67 non-subscribers after spam problems and because patches get reviewed by
0d9dec871b83 cosmetic reformatting (preparation for upcoming changes)
diego
parents: 12419
diff changeset
68 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
69 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
70 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
71 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
72 any mails.
13258
7903766338f7 some new patch policy: compression, mail threading, printf vs mp_msg
diego
parents: 13156
diff changeset
73 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
74 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
75 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
76 big you cannot send it by mail, try splitting it into smaller pieces.
2121
95b8a1e7962d sending patches
arpi
parents:
diff changeset
77
12898
2054ffe13177 Explain how to handle big patches and why uploading patches is bad.
diego
parents: 12812
diff changeset
78 9. 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
79 but unfortunately we are constantly overloaded with work, be it MPlayer-
12602
0d9dec871b83 cosmetic reformatting (preparation for upcoming changes)
diego
parents: 12419
diff changeset
80 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
81 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
82 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
83 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
84 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
85 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
86 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
87 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
88 mail threading.
8432
7b6b7fb76965 small updates
diego
parents: 7645
diff changeset
89
12900
a5df08927328 Wording/spelling suggestions by the Wanderer, merged sections about when to
diego
parents: 12898
diff changeset
90 10. Do not immediately ask for CVS write access. If you have contributed one or
12602
0d9dec871b83 cosmetic reformatting (preparation for upcoming changes)
diego
parents: 12419
diff changeset
91 more nice, acceptable patches and they need maintaining or you want to
0d9dec871b83 cosmetic reformatting (preparation for upcoming changes)
diego
parents: 12419
diff changeset
92 be an MPlayer developer, you'll get CVS write access.
11283
10e0ad4f21b6 _ vs - in option names
diego
parents: 11196
diff changeset
93
12900
a5df08927328 Wording/spelling suggestions by the Wanderer, merged sections about when to
diego
parents: 12898
diff changeset
94 11. 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
95
12900
a5df08927328 Wording/spelling suggestions by the Wanderer, merged sections about when to
diego
parents: 12898
diff changeset
96 12. 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
97 AUTHORS file, include that in your patch.
12106
a79d9b3a83fd cosmetics
diego
parents: 11459
diff changeset
98
13258
7903766338f7 some new patch policy: compression, mail threading, printf vs mp_msg
diego
parents: 13156
diff changeset
99 13. Do not use printf for console output, use our own mp_msg functions instead.
7903766338f7 some new patch policy: compression, mail threading, printf vs mp_msg
diego
parents: 13156
diff changeset
100 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
101 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
102 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
103 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
104 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
105 that has to be translated.
7903766338f7 some new patch policy: compression, mail threading, printf vs mp_msg
diego
parents: 13156
diff changeset
106
2121
95b8a1e7962d sending patches
arpi
parents:
diff changeset
107 Thank you!