Contributing.html

<h1 id="name">NAME</h1>

<p>Joose.Manual.Contributing - How to get involved in Joose</p>

<h1 id="gettinginvolved">GETTING INVOLVED</h1>

<p>Joose is an open project, and we are always willing to accept bug fixes, more tests, and documentation patches. Commit bits are given out freely, and the "STANDARD WORKFLOW" is very simple. 
The general gist is: clone the Git repository, create a new topic branch, hack away, then find a committer to review your changes.</p>

<h1 id="newfeatures">NEW FEATURES</h1>

<p>Joose already has a fairly large feature set, and we are currently not looking to add any major new features to it. If you have an idea for a new feature in Joose, you are invited instead to create a JooseX module first.</p>

<p>At this stage, no new features will even be considered for addition into the core without first being vetted as a JooseX module, unless it is absolutely 100% impossible to implement the feature outside the core.</p>

<p>If you think it is 100% impossible, please come discuss it with us on IRC or via e-mail. However, your feature may need a small hook in the core, or a refactoring of some core modules, and we are definitely open to that.</p>

<p>Joose was built from the ground up with the idea of being highly extensible, and quite often the feature requests we see can be implemented through a couple of small and well placed extensions. Try it, it is much easier then you might think.</p>

<h1 id="people">PEOPLE</h1>

<p>As Joose has matured, some structure has emerged in the process.</p>

<ul>
<li><p>Contributors - people creating a topic or branch</p>

<p>You.</p>

<p>If you have commit access, you can create a topic on the main Joose.git, otherwise either give us your SSH key or create your own clone of the git://git.Joose.perl.org/Joose.git repository or fork of the GitHub mirror.</p></li>
<li><p>Core Committers - people reviewing and merging a branch</p>

<p>These people have worked with the Joose codebase for a while.</p>

<p>They've been responsible for large features or branches and can help review your changes and apply them to the master branch using the basic "APPROVAL WORKFLOW".</p>

<p>They are also fairly well versed in Git, in order to merge the branches with no mistakes (especially when the merge fails), and to provide advice to contributors.</p></li>
<li><p>Cabal - people who can release Joose</p>

<p>These people are the ones who have co-maint on Joose itself and can create a release. They're listed under "CABAL" in Joose in the Joose documentation. They merge from Master to Stable.</p></li>
</ul>

<h1 id="branchlayout">BRANCH LAYOUT</h1>

<p>The repository is divided into several branches to make maintenance easier for everyone involved. The branches below are ordered by level of stability.</p>

<ul>
<li><p>Stable (refs/heads/stable)</p>

<p>The branch from which releases are cut. When making a new release, the release manager merges from master to stable. The stable branch is only updated by someone from the Cabal during a release.</p></li>
<li><p>Master (refs/heads/master)</p>

<p>The branch for new development. This branch is merged into and branched from.</p></li>
<li><p>Branches (refs/heads/*)</p>

<p>Large community branches for big development "projects".</p></li>
<li><p>Topics (refs/heads/topic/*)</p>

<p>Small personal branches that have been published for review, but can get freely rebased. Targeted features that may span a handful of commits.</p>

<p>Any change or bugfix should be created in a topic branch.</p></li>
</ul>

<h1 id="standardworkflow">STANDARD WORKFLOW</h1>

<pre><code>    # update your copy of master
    git checkout master
    git pull --rebase

    # create a new topic branch
    git checkout -b topic/my-feature

    # hack, commit, feel free to break fast forward
    git commit --amend                       # allowed
    git rebase --interactive                 # allowed
    git push --force origin topic/my_feature # allowed
</code></pre>

<p>Then ask for a review/approval (see "APPROVAL WORKFLOW"), and merge to master. If it merges cleanly and nobody has any objections, then it can be pushed to master.</p>

<p>If it doesn't merge as a fast forward, the author of the branch needs to run</p>

<pre><code>    git remote update
    git rebase origin/master # or merge
</code></pre>

<p>and bring the branch up to date, so that it can be merged as a fast forward into master.</p>

<p>No actual merging (as in a human resolving conflicts) should be done when merging into master, only from master into other branches.</p>

<h2 id="preparingatopicbranch">Preparing a topic branch</h2>

<p>Before a merge, a topic branch can be cleaned up by the author.</p>

<p>This can be done using interactive rebase to combine commits, etc, or even git merge --squash to make the whole topic into a single commit.</p>

<p>Structuring changes like this makes it easier to apply git revert at a later date, and encourages a clean and descriptive history that documents what the author was trying to do, 
without the various hangups that happened while they were trying to do it (commits like "oops forgot that file" are not only unnecessary noise, they also make running things like git bisect or git revert harder).</p>

<p>However, by far the biggest benefit is that the number of commits that go into master is eventually reduced, and they are simple and coherent, making it much easier for people maintaining branches to stay up to date.</p>

<p>All large changes should be documented in <a href="Delta.html">Joose.Manual.Delta</a></p>

<h1 id="approvalworkflow">APPROVAL WORKFLOW</h1>

<p>Joose is an open project but it is also an increasingly important one. Many modules depend on Joose being stable. 
Therefore, we have a basic set of criteria for reviewing and merging branches. What follows is a set of rough guidelines that ensures all new code is properly vetted before it is merged to the master branch.</p>

<p>It should be noted that if you want your specific branch to be approved, it is your responsibility to follow this process and advocate for your branch. 
The preferred way is to send a request to the mailing list for review/approval, this allows us to better keep track of the branches awaiting approval and those which have been approved.</p>

<h2 id="smallbugfixesdocpatchesandadditionalpassingtests.">Small bug fixes, doc patches and additional passing tests.</h2>

<p>These items don't really require approval beyond one of the core contributors just doing a simple review.</p>

<h2 id="largerbugfixesdocadditionsandtodoorfailingtests.">Larger bug fixes, doc additions and TODO or failing tests.</h2>

<p>Larger bug fixes should be reviewed by at least one cabal member and should be extensively tested.</p>

<p>New documentation is always welcome, but should also be reviewed by a cabal member for accuracy.</p>

<p>TODO tests are basically feature requests, see our "NEW FEATURES" section for more information on that. If your feature needs core support, create a topic/ branch using the "STANDARD WORKFLOW" and start hacking away.</p>

<p>Failing tests are basically bug reports. You should find a core contributor and/or cabal member to see if it is a real bug, then submit the bug and your test to the <a href="http://code.google.com/p/joose-js/issues/list">issues tracker</a>. 
Source control is not a bug reporting tool.</p>

<h2 id="newuser-facingfeatures.">New user-facing features.</h2>

<p>Anything that creates a new user-visible feature needs to be approved by more then one cabal member.</p>

<p>Make sure you have reviewed "NEW FEATURES" to be sure that you are following the guidelines. Do not be surprised if a new feature is rejected for the core.</p>

<h2 id="newinternalsfeatures.">New internals features.</h2>

<p>New features for Joose internals are less restrictive then user facing features, but still require approval by at least one cabal member.</p>

<p>Ideally you will have run the smolder script to be sure you are not breaking any JooseX module or causing any other unforeseen havoc. If you do this (rather then make us do it), it will only help to hasten your branch's approval.</p>

<h2 id="backwardsincompatiblechanges.">Backwards incompatible changes.</h2>

<p>Anything that breaks backwards compatibility must be discussed by the cabal and agreed to by a majority of the members.</p>

<p>We have a policy for what we see as sane "BACKWARDS COMPATIBILITY" for Joose. If your changes break back-compat, you must be ready to discuss and defend your change.</p>

<h1 id="releaseworkflow">RELEASE WORKFLOW</h1>

<pre><code>    git checkout master
    # edit for final version bumping, changelogging, etc
    # prepare release (test suite etc)
    git commit
    git checkout stable
    git merge master # must be a fast forward
    git push both
    # ship &amp; tag
</code></pre>

<p>Development releases are made without merging into the stable branch.</p>

<h1 id="emergencybugworkflowforimmediaterelease">EMERGENCY BUG WORKFLOW (for immediate release)</h1>

<p>Anyone can create the necessary fix by branching off of the stable branch:</p>

<pre><code>    git remote update
    git checkout -b topic/my-emergency-fix origin/stable
    # hack
    git commit
</code></pre>

<p>Then a cabal member merges into stable:</p>

<pre><code>    git checkout stable
    git merge topic/my-emergency-fix
    git push
    # release
    git checkout master
    git merge stable
</code></pre>

<h1 id="projectworkflow">PROJECT WORKFLOW</h1>

<p>For longer lasting branches, we use a subversion style branch layout, where master is routinely merged into the branch. Rebasing is allowed as long as all the branch contributors are using git pull --rebase properly.</p>

<p>commit --amend, rebase --interactive, etc. are not allowed, and should only be done in topic branches. Committing to master is still done with the same review process as a topic branch, and the branch must merge as a fast forward.</p>

<p>This is pretty much the way we're doing branches for large-ish things right now.</p>

<p>Obviously there is no technical limitation on the number of branches. You can freely create topic branches off of project branches, or sub projects inside larger projects freely. Such branches should incorporate the name of the branch they were made off so that people don't accidentally assume they should be merged into master:</p>

<pre><code>git checkout -b my-project--topic/foo my-project
</code></pre>

<p>(unfortunately Git will not allow my-project/foo as a branch name if my-project is a valid ref).</p>

<h1 id="thepubranch">THE "PU" BRANCH</h1>

<p>To make things easier for longer lived branches (whether topics or projects), the 'pu' branch is basically what happens if you merge all of the branches and topics together with master.</p>

<p>We can update this as necessary (e.g. on a weekly basis if there is merit), notifying the authors of the respective branches if their branches did not merge (and why).</p>

<p>To update 'pu':</p>

<pre><code>    git checkout pu
    git remote update
    git reset --hard origin/master
    git merge @all_the_branches
</code></pre>

<p>If the merge is clean, 'pu' is updated with push --force.</p>

<p>If the merge is not clean, the offending branch is removed from @all_the_branches, with a small note of the conflict, and we try again.</p>

<p>The authors of the failed branches should be told to try to merge their branch into 'pu', to see how their branch interacts with other branches.</p>

<p>'pu' is probably broken most of the time, but lets us know how the different branches interact.</p>

<h1 id="brancharchival">BRANCH ARCHIVAL</h1>

<p>Merged branches should be deleted.</p>

<p>Failed branches may be kept, but consider moving to refs/attic/ (e.g. http://danns.co.uk/node/295) to keep git branch -l current.</p>

<p>Any branch that could still realistically be merged in the future, even if it hasn't had work recently, should not be archived.</p>

<h1 id="teststeststests">TESTS, TESTS, TESTS</h1>

<p>If you write any code for Joose, you must add tests for that code. If you do not write tests then we cannot guarantee your change will not be removed or altered at a later date, as there is nothing to confirm this is desired behavior.</p>

<p>If your code change/addition is deep within the bowels of Joose and your test exercises this feature in a non-obvious way, please add some comments either near the code in question or in the test so that others know.</p>

<p>We also greatly appreciate documentation to go with your changes, and an entry in the Changes file. Make sure to give yourself credit!</p>

<h1 id="backwardscompatibility">BACKWARDS COMPATIBILITY</h1>

<p>Change is inevitable, and Joose is not immune to this. We do our best to maintain backwards compatibility, but we do not want the code base to become overburdened by this. 
This is not to say that we will be frivolous with our changes, quite the opposite, just that we are not afraid of change and will do our best to keep it as painless as possible for the end user.</p>

<p>The rule is that if you do something that is not backwards compatible, you must do at least one deprecation cycle (more if it is larger change). 
For really larger or radical changes dev releases may be needed as well (the Cabal will decide on this on a case-per-case basis).</p>

<p>The preference with regard to deprecation is to warn loudly and often so that users will have time to fix their usages.</p>

<p>All backwards incompatible changes must be documented in <a href="Delta.html">Joose.Manual.Delta</a>. Make sure to document any useful tips or workarounds for the change in that document.</p>

<h1 id="author">AUTHOR</h1>

<p>Nickolay Platonov <a href="mailto:nickolay8@gmail.com">nickolay8@gmail.com</a></p>

<p>Heavily based on the original content of Moose::Manual, by </p>

<pre><code>    Stevan Little &lt;stevan@iinteractive.com&gt;

    Chris (perigrin) Prather

    Yuval (nothingmuch) Kogman
</code></pre>

<h1 id="copyrightandlicense">COPYRIGHT AND LICENSE</h1>

<p>Copyright (c) 2008-2009, Malte Ubl, Nickolay Platonov</p>

<p>All rights reserved.</p>

<p>Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:</p>

<ul>
<li>Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.</li>
<li>Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.</li>
<li>Neither the name of Malte Ubl nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. </li>
</ul>

<p>THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. </p>