doc/www/patches.html

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