Developer Central

The purpose of this page is to give a link to all kinds of resources that contain information valuable to current and future developers of xoreos.

The source repository

The main xoreos source repositories are hosted on GitHub. Please see the Git page on details on how the repositories are structured and how to retrieve the code.

Compilation

See the Compiling xoreos and Compiling xoreos-tools pages for information on how to compile our source code on various operating systems.

Community

We strive to be a friendly and open development community. Therefore, we have adopted a Code of Conduct guiding us. By participating in this project you agree to abide by its terms.

Our main place for organizing and socializing is the #xoreos channel on Freenode IRC. You will find most of the developers idling there, happy to answer any questions you might have. If you plan to become a frequent contributor, please consider regularly joining this channel as well.

However, there is not public log bot in #xoreos, so there is no public, permanent record. Therefore, discussions about far reaching changes in the codebase are best held on our mailing list. Contributors are encouraged to subscribe to this list.

If you intend to work on a feature, or otherwise contribute to xoreos, please notify us before-hand, so that unnecessary, accidentally doubling of work can be avoided.

Reporting bugs

Bugs should be reported on the GitHub issue tracker. If the bug concerns xoreos itself, use the one for xoreos, if the bug concerns the xoreos-tools, use the one for xoreos-tools. Likewise, all the other repositories have issue tracking enabled.

Code style

We have Code Formatting Conventions you are expected to follow. Patches and pull requests that do not follow these conventions will be rejected or at least delayed until they are cleaned up to comply.

Commit guidelines

Please read the Commit Guidelines. We want to keep our project history clean and readable.

Branches

Do not work directly on the master branch. Instead, use feature branches, one for each new feature you are working on. This ensures that each feature has its own, clean history that can be reviewed more easily. Once the feature has been merged into the main development tree, you are of course free to delete your feature branch again.

Pull Requests

If you do not have push permissions to the official xoreos repositories, and especially if you're a first-time contributor, we prefer to receive your changes as a pull request on GitHub. This requires you to have/register a GitHub account, fork our repository, commit your changes to a branch and then issue a Pull Request.

Please only add commits belonging to this one feature to the pull requests; do not intersperse them with unrelated changes. Also try to actively tidy your history: combine related commits with interactive rebasing, separate monolithic commits, etc. Feel free to force-push to your feature branch to tidy your history.

Before and during the review process, please keep up to date with the xoreos master branch by rebasing your changes onto the current master.

Pushing to the official repositories

Once we've made sure that you understood and can follow the style and commit guidelines and you expressed interest in further contributing to xoreos, we will be happy to have you join the xoreos development team, and grant you push permissions to the official repositories. You are then expected to continue to follow these guidelines out of your own accord, without the need for intervention by other developers. If you are unsure about how a specific case interact with the guidelines, please feel free to ask.

To avoid people accidentally working on the same feature, or otherwise stepping on each others' toes, consider announcement what you are working on in the IRC channel or the mailing list.

Continuous Integration

The public xoreos repositories are build by two Continuous Integration services on every push: Travis CI (for GNU/Linux, using both the autotools and the CMake build systems and also using both gcc and clang) and AppVeyor (for Windows, using Microsoft Visual Studio). If a compilation error occurs, the build failure announced is on our IRC channel, so that it may be fixed quickly. Pull Requests are also run through these CI services and we like to have all failures fixed before merging.

Unit tests

The xoreos repositories also provide unit tests for many common classes. These are build and run right after the main binaries on every push, by the CI services we use. A failure in one of these unit tests leads to the build being treated as failed. That way, it's immediately obvious when we break anything.

All xoreos developers are advised to run these unit tests themselves while writing code that touches the common code. In both of our build systems, "make check" does exactly this.

When writing new common classes, or adding functionality to existing ones, also writing new unit tests checking the new functionality is hugely appreciated.

Reverse engineering help

For people starting out with reverse engineering, here are a few useful resources:

• The HOWTO-Reverse Engineering page in ScummVM's wiki
• REWiki contains a collection of game reverse engineering knowledge. They have a hints page as well
• XentaxWiki focuses on game file formats. They too have a guide page
• For audio and video formats, there's MultimediaWiki, which is associated with the ffmpeg and libav projects

To do list

Our Main TODO list contains a rambly, non-exhaustive collection of things left to do.