-
Get the source code
Torque 3D's source code lives at TorqueGameEngines/Torque3D. To clone a copy of the source code, you will need a git client. We recommend the official client. Once you have installed Git, you should follow GitHub's forking tutorial to make your own repository to which you can commit your code.
The repository has two main branches:
Preview4_0
anddevelopment
. We recommend that you do not commit any of your own code into these branches, but simply pull down changes from TorqueGameEngines 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.Pull-request guide
So you want to make a pull request
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 this tutorial by GitHub.
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.
Pull request rules
Pull requests not adhering to these rules cannot be accepted, so pay attention!
- Obviously, your contribution cannot contain any code that is not legally compatible with Torque 3D's MIT license.
- Contributions must adhere to our code style guidelines.
- Pull-requests against the master branch cannot be accepted. All requests must go to development, or an appropriate topic or maintenance branch.
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.
Pull request guidelines
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!
- Each pull request should be focused and concise. 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.
- 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.
- 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.
The pull request process
- You make a pull-request to the TorqueGameEngines/Torque3D repository.
- 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 enhancement to an existing feature) is simply something that could be better (for example, a performance improvement).
- 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!
- 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.
- If it passes final review, your pull-request is merged! Congratulations.
Version policy
We maintain an X.Y.z version scheme similar to that of Semantic Versioning. However, since our API is less well-defined, the table below describes what we mean by the three version number components.
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.
X
Major version numberThe major version number denotes a single version of our client-facing 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. Y
Minor version numberThe 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 new features, but we will not make breaking changes to existing ones. z
Patch numberPatches denote minor updates to stability or correctness that do not change the engine API in a significant way. Issues and feature requests
Reporting a bug
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 GitHub issue tracker 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:
- Your platform and compiler version
- A description of what currently happens, and what should or should not happen.
- Steps to reproduce the bug.