doc/www/patches.php

   1 <? include ("barry.inc"); ?>
   2
   3 <? createHeader("Submitting Patches"); ?>
   4
   5 <? createSubHeader("Coding Guidelines"); ?>
   6
   7 <p>If you are submitting code, please have a look at the
   8 <? createLink("codingguide", "Coding Guidelines page"); ?>.</p>
   9
  10 <p>Please keep some things in mind when preparing your patches
  11 for submission:
  12 <ul>
  13         <li>use one patch per logical change</li>
  14         <li>test all coding changes</li>
  15         <ul>
  16                 <li>If it is a change to the build system, make sure that
  17                         the test/buildtest.sh script still works.</li>
  18         </ul>
  19         <li>include some commentary above your patch in your email</li>
  20         <li>when mailing patches, try to keep one patch per email</li>
  21         <li>do not cut and paste patches... either read them in
  22                 directly to your mail body (preferred),
  23                 or send as an attachment</li>
  24         <li>add a [PATCH] prefix to your subject line</li>
  25 </ul>
  26 </p>
  27
  28
  29 <? createSubHeader("Why Submit Patches?"); ?>
  30
  31 <p>Submitting your changes via patch is a good thing.  It may seem like
  32 an extra bit of work to create a patch and post it to the mailing list,
  33 or to make your work available in a public git repo, but there are good
  34 reasons why Open Source works that way:</p>
  35
  36 <ul>
  37         <li>Patches tell the maintainer that you <b>want</b> your change
  38                 to be added to the tree.  It is often too easy for busy
  39                 programmers to misunderstand someone's intentions if
  40                 they just send a random file.  If intentions are not
  41                 clear, work gets dropped on the floor.</li>
  42         <li>Patches show that you have worked with the source code,
  43                 and hopefully have tested your change.</li>
  44         <li>Patches show that you have given some thought to where
  45                 your changes should go in the tree.</li>
  46         <li>Patches to a public mailing list encourage peer review, and show
  47                 that you are ok with your code being included in a public
  48                 project.</li>
  49         <li>Patches to a public mailing list or a public repository become
  50                 part of history, showing who did what, and when.</li>
  51         <li>Patches usually get top priority from developers.</li>
  52         <li>Patches make life easier for the developers, freeing up their
  53                 time for more features and bug fixes.</li>
  54         <li>Patches turn you into a developer.  Your name can be added
  55                 to the AUTHORS file.</li>
  56 </ul>
  57
  58
  59 <? createSubHeader("Generating Patches"); ?>
  60
  61 <p>Generating patches depends on the method you used to get the source code.
  62 <ul>
  63         <li>If you are using a tarball, expand the tarball once into
  64                 a pristine directory, and again into your "working
  65                 directory."  When you are finished and
  66                 ready to patch, do:
  67 <pre>
  68         cd barry-work
  69         ./buildgen.sh cleanall
  70         cd ..
  71         diff -ruN barry-orig barry-work > patchfile
  72 </pre>
  73         </li>
  74
  75         <li>If you are using the git tree, you can make your changes
  76                 in your own branch, and then create patches for each
  77                 commit you've made:
  78 <pre>
  79         cd barry-git
  80         git format-patch origin/master
  81 </pre>
  82
  83         </li>
  84
  85 </ul>
  86
  87
  88 <? createSubHeader("Methods for Submitting Patches"); ?>
  89
  90 <p>Submitting changes can happen in one of three methods:
  91
  92 <ul>
  93         <li>Send a patch to the
  94         <a href="http://sourceforge.net/mail/?group_id=153722">mailing list</a>.
  95         </li>
  96
  97         <li>Publish your own git repository (perhaps by creating a
  98                 forked tree on
  99                 <a href="http://repo.or.cz/">repo.or.cz</a>)
 100                 and notify the mailing list, indicating the
 101                 branch you want people to pull from when
 102                 you're ready.</li>
 103
 104         <li>Use the "mob" branch on <a href="http://repo.or.cz/w/barry.git">
 105                 Barry's git repository</a>, and....
 106                 send a notification to the mailing list.</li>
 107 </ul>
 108 </p>
 109
 110
 111 <? createSubHeader("Creating a Forked Tree on repo.or.cz"); ?>
 112
 113 <p>The git repo site repo.or.cz lets anyone create a forked tree based
 114 off the official Barry repo.  This saves space on repo.or.cz, and
 115 adds your fork to a list at the bottom of the official Barry page.</p>
 116
 117 <p>This way, users and developers can look at everyone's changes and
 118 test and mix them as needed.</p>
 119
 120 <p>To create a forked tree, visit the <a href="http://repo.or.cz/w/barry.git">
 121 Barry repo</a> and click "fork" at the top.</p>
 122
 123
 124
 125 <? createSubHeader("Using the Mob Branch"); ?>
 126
 127 <p>The public git repository service at repo.or.cz provides an interesting
 128 feature, which allows anyone to push to a "mob" branch of a repository,
 129 if so configured by the admin.</p>
 130
 131 <p> It would go something like this:
 132 <pre>
 133         # clone with mob user
 134         git clone git+ssh://mob@repo.or.cz/srv/git/barry.git barry
 135
 136         cd barry
 137         git checkout -b mob origin/mob
 138         git diff origin/master..mob             # make sure master == mob
 139         &lt;make changes&gt;
 140         git add ... && git commit
 141         git push origin mob
 142         &lt;send email to the list, include the SHA1 sum of the commit&gt;
 143 </pre>
 144 </p>
 145
 146 <p> This is a novel idea, as well as a security risk for anyone who blindly
 147 runs whatever is in the mob branch.  Hence the recommended diff check
 148 above, to make sure you're working on an official branch.</p>
 149
 150 <p> The mob user can only push to the mob branch, so all other branches
 151 are read-only, and have been reviewed at least once by the project
 152 maintainer.</p>
 153
 154 <p>  But the mob branch frees people up to use git, who may not have
 155 their own hosting, or who may not want to bother setting up their
 156 own git repo.  People can use it to collaborate on a feature as well.
 157 Let your imagination run wild.</p>
 158
 159 <p>You can read more about the ideas behind the mob branch at
 160 <a href="http://repo.or.cz/h/mob.html">the repo.or.cz mob page</a></p>
 161