Torque3D/contribute/index.html

---
layout: page
title: Contribute | Torque 3D
root: ..
---

<div class="banner"><div class="container">
    <h2 id="get-the-source-code">Get the source code</h2>
</div></div>

<div class="container">
    <p>
    Torque 3D's source code lives at <a href="https://github.com/GarageGames/Torque3D">GarageGames/Torque3D</a>.
    To clone a copy of the source code, you will need a <a href="http://git-scm.com/">git</a>
    client. We recommend the <a href="http://git-scm.com/downloads">official client</a>. Once you
    have installed Git, you should follow
    <a href="https://help.github.com/articles/fork-a-repo">GitHub's forking tutorial</a>
    to make your own repository to which you can commit your code.
    </p>

    <p>
    The repository has two main branches: <code>master</code> and <code>development</code>. We
    recommend that you do <em>not</em> commit any of your own code into these branches, but
    simply pull down changes from GarageGames' repository into them. You can maintain
    your own branch (perhaps named after your GitHub username, or the game you're working on)
    and merge changes into it as you see fit.
    </p>

    <p>
    We also have a repository for <a href="https://github.com/GarageGames/Torque3D-Wiki">Torque 3D's Github wiki</a>.
    Feel free to fork and pull-request to its <code>master</code> branch if you
    want to submit new documentation, tutorials, or make corrections to existing
    content.
    </p>
</div>

<div class="banner"><div class="container">
    <h2 id="pull-request-guide">Pull-request guide</h2>
</div></div>

<div class="container">
    <h3>So you want to make a pull request</h3>
    <p>
    Pull requests are the way that community members like you can get your code
    pulled into the official Torque 3D repository for everyone else to use. We
    accept community contributions that align with our vision for the engine -
    especially bug fixes, enhancements to existing features, and revisions of
    old, slow, or ugly code. Pull requests are the way that code gets reviewed
    before it's accepted into the engine - even code that we, the Steering Committee,
    write ourselves.
    For a technical tutorial on how to submit a pull request, check out
    <a href="https://github.com/GarageGames/Torque3D/wiki/How-To:--Submit-A-Pull-Request">this page in our wiki</a>, or
    <a href="https://help.github.com/articles/using-pull-requests">this tutorial by GitHub</a>.
    </p>

    <p>
    In order to ensure the quality of the engine code going into the future, we
    have strict rules about what code we can and cannot accept. We also have
    some soft guidelines that inform our decision-making progress in trickier
    cases.
    </p>

    <h3>Pull request rules</h3>
    <p>
    Pull requests not adhering to these rules <i>cannot</i> be accepted, so pay attention!
    </p>

    <ul>
        <li>Obviously, your contribution cannot contain any code that is not
        legally compatible with Torque 3D's MIT license. In addition, to legally
        protect the engine and everyone affiliated with it, we require that all
        contributors create an account on
        <a href="http://garagegames.com">GarageGames.com</a> and sign the Open
        Source Software Agreement there. For more information on the OSSA, please visit
        <a href="https://github.com/GarageGames/Torque3D/wiki/Contributing#open-source-software-agreement">this page in our wiki</a>.</li>

        <li>Contributions must adhere to our
        <a href="https://github.com/GarageGames/Torque3D/wiki/Code-Style-Guidelines">code style guidelines</a>.</li>

        <li>Pull-requests against the master branch cannot be accepted. All requests
        must go to development, or an appropriate topic or maintenance branch.</li>
    </ul>

    <p>
    In many cases, if any of these rules are breached, we will first ask the contributor
    to resubmit their pull request, or add commits to it that resolve our issues.
    In exceptional cases (i.e., we really really like your work), a committee
    member may perform that work themselves.
    </p>

    <h3>Pull request guidelines</h3>
    <p>
    Here are some of the things we look for in a great pull request. These aren't
    hard-and-fast rules, but following these guidelines will increase the chances
    that your request is pulled!
    </p>

    <ul>
        <li>Our favourite requests are ones that work directly towards the goals
        laid out in our <a href="{{page.root}}/engine#roadmap">roadmap</a>. We
        are more likely to help out and fix slightly broken pull requests if
        they align with our goals, and chances are your request will move faster
        through our process.</li>

        <li>Each pull request should be <i>focused</i> and <i>concise</i>. If
        it has a very clear intent and a small set of changes towards a specific
        goal, it's easy for us to decide whether we want it, and to then test it
        and make sure it works as advertised and doesn't break things.</li>

        <li>If you're fixing a bug, we need you to provide steps to reproduce it
        so we can verify that exists and that your patch actually does fix it.
        We'd also appreciate platform and compiler information.</li>

        <li>We like each pull request to have a reasonable revision history - not
        too many small commits with typo fixes, for example. Sometimes, we may ask
        contributors to rebase large numbers of commits into a single commit
        before the request is pulled.</li>
    </ul>

    <h3>The pull request process</h3>
    <ol>
        <li>You make a pull-request to the GarageGames/Torque3D repository.</li>

        <li>We tag the request appropriately according to its status as a new feature,
        a bug/fix or a defect/enhancement. The difference between the latter two is
        that a bug (which you may be submitting a fix for) is advertised functionality
        that does not work correctly, or a situation that causes a crash. A defect
        (or an ehnahcement to an existing feature) is simply something that <em>could</em>
        be better (for example, a performance improvement).</li>

        <li>One or more members of the Committee or the general community review your
        request, adding comments if they see any problems. This code-review process
        may take some time as we need to consider a variety of factors when considering
        whether a pull request is appropriate. We (and others) may point out technical
        flaws or suggest ways we would prefer the issue to be solved. We will also
        pull down your code and test it locally to verify that it does as advertised!</li>

        <li>If all goes well, the 'Final Review' label will be applied to your request.
        This is a formality stage that collects pull requests we feel are nearly ready
        to be merged, and allows reviews to focus their attention better on imminent
        new code. At this stage, if only one member of the Committee has been involved
        in reviewing the code, another must become involved.</li>

        <li>If it passes final review, your pull-request is merged! Congratulations.</li>
    </ol>
</div>

<div class="banner"><div class="container">
    <h2 id="version-policy">Version policy</h2>
</div></div>

<div class="container">
    <p>
    We maintain an <b>X.Y.z</b> version scheme similar to that of
    <a href="http://semver.org/">Semantic Versioning</a>. However, since our API is
    less well-defined, the table below describes what we mean by the three
    version number components.
    </p>

    <p class="alert alert-warning">
    Note that this new versioning policy is different to the one adopted by the first
    and second Steering Committees, and applies only to engine versions 3.5.2 and above.
    </p>

    <table class="borderless versioning table">
        <tr>
            <td><b>X</b><br/>Major version number</td>
            <td>The major version number denotes a single version of our <em>client-facing</em>
            API, which refers to the script and editor capabilities exposed to binary-only
            users of the engine, as well as major parts of the internal C++ API, such
            as the class hierarchy.</td>
        </tr>

        <tr>
            <td><b>Y</b><br/>Minor version number</td>
            <td>The minor version number refers to the set of features in a given API. Across
            a minor version number change, we may refactor code, fix bugs, or introduce
            <em>new</em> features, but we will not make breaking changes to existing ones.</td>
        </tr>

        <tr>
            <td><b>z</b><br/>Patch number</td>
            <td>Patches denote minor updates to stability or correctness that do not change
            the engine API in a significant way.</td>
        </tr>
    </table>
</div>

<div class="banner"><div class="container">
    <h2 id="issues-and-requests">Issues and feature requests</h2>
</div></div>

<div class="container">
    <h3>Reporting a bug</h3>
    <p>
    If you find a bug in the engine that you're sure you didn't cause (don't
    worry, we cause bugs all the time ourselves!), please use the
    <a href="https://github.com/GarageGames/Torque3D/issues">GitHub issue tracker</a>
    to let us know. Please have a bit of a look at recent issues before you
    do, in case someone has already noticed the same problem. And remember to
    provide the following information:
    </p>

    <ul>
        <li>Your platform and compiler version</li>

        <li>A description of what currently happens, and what <em>should</em> or
        should not happen.</li>

        <li><b>Steps to reproduce the bug.</b></li>
    </ul>

    <h3>Requesting a new feature</h3>
    <p>
    We use a <a href="http://garagegames.uservoice.com/">UserVoice</a> forum to monitor
    feature requests from users. Before making a forum post or starting a new request,
    check to see if your feature has already been requested.
    </p>
</div>