Contributing to libgdx is easy:
- Fork libgdx on http://github.com/libgdx/libgdx
- Learn how to [[Work with the source | Running Demos & Tests]]
- Hack away and sent a pull request on Github!
If you modify a public API, or add a new one, make sure to add these changes to the CHANGES file in the root of the repository. In addition to the CHANGES file, such modifications are also published on the blog and on Twitter to reach all of the community.
If you want to poll the brains of other devs, either send a pull request and start a conversation on Github, or start a new thread in this sub-forum. You will need special forum permissions, write an e-mail to contact at badlogicgames dot com and tell me your forum id. You should also subscribe to that forum via e-mail, there's a button at the bottom of the page. You can also drop by on IRC (irc.freenode.org, #libgdx), where most core devs are lurking.
Libgdx is licensed under the Apache 2.0 license. Before we can accept code contributions, we need you to sign our contributor license agreement. Just print it out, fill in the blanks and send a copy to [email protected], with the subject [Libgdx] CLA.
Signing the CLA will allow us to use and distribute your code. This is a non-exclusive license, so you retain all rights to your code. It's a fail-safe for us should someone contribute essential code and later decide to take it back.
If you work on libgdx code, we require you to use the Eclipse formatter located in the root directory of the repository.
Failure to use the formatter will result in Nate being very upset.
Libgdx does not have an official coding standard. We mostly follow the usual Java style, and so should you.
A few things we'd rather not like to see:
- underscores in any kind of identifier
- Hungarian notation
- Prefixes for fields or arguments
- Curlies on new lines
- Conditional block bodies without curlies
If you modify an existing file, follow the style of the code in there.
If you create a new file, make sure to add the Apache file header, as seen here.
If you create a new class, please add at least class documentation that explains the usage and scope of he class. You can omit Javadoc for methods that are self-explanatory.
If your class is explicitly thread-safe, mention it in the Javadoc. The default assumption is that classes are not thread-safe, to reduce the amount of costly locks in the code base.
Libgdx is meant to run on both desktop and mobile platforms, including browsers (JavaScript!). While the desktop HotSpot VM can take quite a beating in terms of unnecessary allocations, Dalvik and consorts don't.
A couple of guidelines:
- Avoid temporary object allocation wherever possible
- Do not make defensive copies
- Avoid locking, libgdx classes are by default not thread-safe unless explicitly specified
- Do not use boxed primitives
- Use the collection classes in the com.badlogic.gdx.utils package
- Do not perform argument checks for methods that may be called thousands of times per frame
- Use pooling if necessary, if possible, avoid exposing the pooling to the user as it complicates the API
Most of the libdgx team members are Git novices, as such we are just learning the ropes ourself. To lower the risk of getting something wrong, we'd kindly ask you to keep your pull requests small if possible. A change-set of 3000 files is likely not to get merged.
We do open new branches for bigger API changes. If you help out with a new API, make sure your pull request targets that specific branch.
Pull requests for the master repository will be checked by multiple core contributors before inclusion. We may reject your pull requests to master if we do not deem them to be ready or fitting. Please don't take offense in that case. Libgdx is used by thousands of projects around the world, we need to make sure things stay somewhat sane and stable.