doc/www/patches.php

   1 <? createHeader("Submitting Patches"); ?>
   2
   3 <? include ("barry.inc"); ?>
   4
   5
   6 <div class="subHeader">Coding Guidelines</div>
   7
   8 <p>If you are submitting code, please have a look at the
   9 <? createLink("codingguide", "Coding Guidelines page"); ?>.</p>
  10
  11 <p>Please keep some things in mind when preparing your patches
  12 for submission:
  13 <ul>
  14         <li>use one patch per logical change</li>
  15         <li>test all coding changes</li>
  16         <ul>
  17                 <li>If it is a change to the build system, make sure that
  18                         the test/buildtest.sh script still works.</li>
  19         </ul>
  20         <li>include some commentary above your patch in your email</li>
  21         <li>when mailing patches, try to keep one patch per email</li>
  22         <li>do not cut and paste patches... either read them in
  23                 directly to your mail body (preferred),
  24                 or send as an attachment</li>
  25         <li>add a [PATCH] prefix to your subject line</li>
  26 </ul>
  27
  28
  29 <div class="subHeader">Generating Patches</div>
  30
  31 <p>Generating patches depends on the method you used to get the source code.
  32 <ul>
  33         <li>If you are using a tarball, expand the tarball once into
  34                 a pristine directory, and again into your "working
  35                 directory."  When you are finished and
  36                 ready to patch, do:
  37 <pre>
  38         cd barry-work
  39         ./buildgen.sh cleanall
  40         cd ..
  41         diff -ruN barry-orig barry-work > patchfile
  42 </pre>
  43         </li>
  44
  45         <li>If you are using CVS, make your changes in your working
  46                 directory, and then do:
  47 <pre>
  48         cd barry-cvs
  49         ./buildgen.sh cleanall
  50         cvs diff -u > patchfile
  51         grep ^? patchfile
  52 </pre>
  53                 Any new files that you've added to your tree will need
  54                 to be attached to your patch email, as CVS has no
  55                 way to add files without write access to the repository.
  56                 <br/><br/></li>
  57
  58         <li>If you are using the git tree, you can make your changes
  59                 in your own branch, and then create patches for each
  60                 commit you've made:
  61 <pre>
  62         cd barry-git
  63         git format-patch origin/master
  64 </pre>
  65
  66         </li>
  67
  68 </ul>
  69
  70
  71 <div class="subHeader">Methods for Submitting Patches</div>
  72
  73 <p>Submitting changes can happen in one of three methods:
  74
  75 <ul>
  76         <li>Send a patch to the
  77         <a href="http://sourceforge.net/mail/?group_id=153722">mailing list</a>.
  78         </li>
  79
  80         <li>Publish your own git repository (perhaps on
  81                 <a href="http://repo.or.cz/">repo.or.cz</a>)
  82                 and notify the mailing list, indicating the
  83                 branch you want people to pull from when
  84                 you're ready.</li>
  85
  86         <li>Use the "mob" branch on <a href="http://repo.or.cz/w/barry.git">
  87                 Barry's git repository</a>, and....
  88                 send a notification to the mailing list.</li>
  89 </ul>
  90 </p>
  91
  92
  93 <div class="subHeader">Using the Mob Branch</div>
  94
  95 <p>The public git repository service at repo.or.cz provides an interesting
  96 feature, which allows anyone to push to a "mob" branch of a repository,
  97 if so configured by the admin.</p>
  98
  99 <p> It would go something like this:
 100 <pre>
 101         # clone with mob user
 102         git clone git+ssh://mob@repo.or.cz/srv/git/barry.git barry
 103
 104         cd barry
 105         git checkout -b mob origin/mob
 106         git diff origin/master..mob             # make sure master == mob
 107         &lt;make changes&gt;
 108         git add ... && git commit
 109         git push origin mob
 110         &lt;send email to the list, include the SHA1 sum of the commit&gt;
 111 </pre>
 112 </p>
 113
 114 <p> This is a novel idea, as well as a security risk for anyone who blindly
 115 runs whatever is in the mob branch.  Hence the recommended diff check
 116 above, to make sure you're working on an official branch.</p>
 117
 118 <p> The mob user can only push to the mob branch, so all other branches
 119 are read-only, and have been reviewed at least once by the project
 120 maintainer.</p>
 121
 122 <p>  But the mob branch frees people up to use git, who may not have
 123 their own hosting, or who may not want to bother setting up their
 124 own git repo.  People can use it to collaborate on a feature as well.
 125 Let your imagination run wild.</p>
 126
 127 <p>You can read more about the ideas behind the mob branch at
 128 <a href="http://repo.or.cz/mob.html">the repo.or.cz mob page</a></p>
 129