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