DOCS/tech/patches.txt

   1 Sending patches:
   2 ~~~~~~~~~~~~~~~~
   3
   4 Note: We know our rules place a burden on you, but rest assured that
   5 maintaining a big and complex software project is even harder, so please
   6 accept our rules. We cannot afford to spend our time fixing buggy, broken or
   7 outdated patches. The closer you follow our rules the higher is the probability
   8 that your patch will be included.
   9
  10  0. Do not send complete files. These need to be diffed by hand to see the
  11     changes, which makes reviews harder and less likely to occur. Besides as
  12     soon as one of the files changes, your version becomes harder to apply,
  13     thus reducing its chances of being accepted.
  14
  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.
  18
  19  2. Make unified diffs ('svn diff' or 'diff -Naur'). Unified diffs can be
  20     applied easily with 'patch'. This is much harder with other diff types.
  21     Besides, unified diffs are more readable and thus easier to review.
  22
  23  3. Create the diff from the root of the MPlayer source tree, this makes the
  24     diff easier to apply as it saves the step of searching for and changing
  25     to the correct directory.
  26
  27  4. Test the functionality of your patch. We'll *refuse* it if it breaks
  28     something, even if it extends other features!
  29
  30  5. Read your patch. We'll *refuse* it if it changes indentation of the
  31     code or if it does tab/space conversion or other cosmetic changes!
  32
  33     NOTE: If you already wrote some code and did cosmetic changes, you can
  34     use 'diff -uwbBE' to help you remove them. Don't forget to check the
  35     patch to make sure diff didn't ignore some important change and remove
  36     any remaining cosmetics!
  37     To use these options directly with svn, use this command:
  38     svn diff --diff-cmd diff -x -uwbBE
  39
  40  6. Comment parts that really need it (tricky side-effects etc).
  41     Always document string operations! Comment on what you are doing
  42     and why it is safe. This makes it easy to review and change your
  43     code if needed. Commenting trivial code not required.
  44     Comments must be English!
  45
  46  7. If you implement new features, add or change command line switches or
  47     modify the behavior of existing features, please do not forget to also
  48     update the documentation. The documentation maintainers will assist you
  49     in doing this. Updating the English documentation is enough. If you
  50     speak several languages you are of course welcome to update some of the
  51     translations as well.
  52
  53  8. If you make independent changes, try to send them as separate patches
  54     in separate mails. Likewise, if your patch is very big, try splitting
  55     it into several self-contained pieces. Each part can then be reviewed
  56     and committed separately. Logical units should stay together, though,
  57     i.e. do not send a patch for every file or directory you change.
  58
  59  9. Send your patch to the mplayer-dev-eng mailing list as a base64-encoded
  60     attachment with the subject line:
  61     '[PATCH] very short description of the patch'.
  62     In the mail, describe in a few sentences what you change and why.
  63     The subject line is very important if you do not want your patch to get
  64     lost in the noise. We need the uppercase [PATCH] to be able to search
  65     for unapplied patches, so please use it.
  66     Do not send your patch as a reply to some other unrelated mail, compose
  67     a new message, otherwise it will probably get overlooked.
  68     Do not compress your patch unless it is larger than 80k or if you know
  69     that your mailer messes up (reformats) text attachments. It only makes
  70     handling the patch more difficult. If you have to compress your patch,
  71     use either bzip2, gzip or zip to compress it, not a different format.
  72     You have to subscribe to mplayer-dev-eng since we blocked postings from
  73     non-subscribers after spam problems and because patches get reviewed by
  74     the developers on the list. We want you to be available for discussing
  75     your code, you might be asked to make modifications before we accept it.
  76     Don't worry, mplayer-dev-eng is not high traffic and you can subscribe
  77     but unset the "Mail delivery" option so that you can post without getting
  78     any mails.
  79     Do not upload the patch to a web or FTP site, send it directly to the
  80     mailing list. The fewer steps it takes us to get at the patch the higher
  81     the likelihood for it to get reviewed and applied. If your patch is so
  82     big you cannot send it by mail, try splitting it into smaller pieces.
  83
  84 10. Give us a few days to react. We try to review patches as fast as possible,
  85     but unfortunately we are constantly overloaded with work, be it MPlayer-
  86     related or from our day to day lives. If your patch seems to be ignored,
  87     send a reminder asking for opinions as a reply to the original patch and
  88     mention that you got ignored. We are interested in your work and will
  89     eventually either accept it or reject it with an explanation of what we
  90     disliked about your patch. We will often ask you to make changes to your
  91     patch to make it acceptable. Implement them if you want to see your patch
  92     applied and send the update to the mailing list. Remember that updates and
  93     reminders must be sent as replies to the original patch to preserve proper
  94     mail threading.
  95
  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.
  99
 100 12. For consistency reasons, all option names must use '-' instead of '_'.
 101
 102 13. If you make a nontrivial contribution and wish to be mentioned in the
 103     AUTHORS file, include that in your patch.
 104
 105 14. Do not use printf for console output, use our own mp_msg functions instead.
 106     For the output to be translated (which includes all messages of level
 107     MSGL_HINT and below), put the strings in help/help_mp-en.h. If you change
 108     strings, remove the occurrences of these strings from the translations.
 109     There may be (compilation) trouble if outdated translations remain in place
 110     and translators will pick up changes more easily if they see a new message
 111     that has to be translated.
 112
 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.
 116     Please always resend patches as replies to the original mail to keep
 117     the thread with the discussion together.
 118
 119 Thank you!