Developer Central: Difference between revisions

From xoreos Wiki
Jump to navigation Jump to search
(Beating back typo gremlins)
(→‎Reverse engineering help: Use Internet Archive links for the REWiki, since it seems to be dead :()
 
(13 intermediate revisions by the same user not shown)
Line 1: Line 1:
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 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 ==


== Getting started ==
The main xoreos source repositories are hosted on [https://github.com/xoreos/ GitHub]. Please see the [[Git]] page on details on how the repositories are structured and how to retrieve the code.
* The first thing you need to be able to do is [[Git#Retrieving_the_code|get the xoreos code]] from our [[Git]] repository.
* Then you should [[Compiling xoreos|compile xoreos]].


That was easy, right? Here are some more tips:
== Compilation ==


* Before you write/submit code, '''you must read''' our [[Code Formatting Conventions]].<br>Patches which do not follow them will be rejected or at least delayed until they are cleaned up to comply to them.
See the [[Compiling xoreos]], [[Compiling xoreos-tools]] and [[Compiling Phaethon]] pages for information on how to compile our source code on various operating systems.
* If you have write (push) access to our repository, you are expected to have read and to comply with our [[Commit Guidelines]].<br>Also, please read the tips for using Git here: [http://wiki.scummvm.org/index.php/Git_tips Git tips].<br>In particular, note the use of feature branches, when working on refactoring or other large connected changes, rather than committing directly to scummvm/master.
* If you do not have write (push) access to our repository, you should submit your contributions by the following method:
** Using a [https://help.github.com/articles/using-pull-requests Github Pull Request].<br> This requires you to have/register a github account, fork our repository, commit your changes to a branch and then issue a Pull Request.<br>This is the current preferred method as it is easier for the team to review, discuss and amend prior to merging.<br>You are expected to have read and to comply with our [[Commit Guidelines]].
* For those starting out with reverse engineering, check out ScummVM's [http://wiki.scummvm.org/index.php/HOWTO-Reverse_Engineering Reverse Engineering HOWTO].


== Community ==
We strive to be a friendly and open development community. Therefore, we have adopted a [https://github.com/xoreos/xoreos/blob/master/CODE_OF_CONDUCT.md 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 [[IRC channel|#xoreos channel on Libera 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 [[Mailing lists|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 [https://github.com/xoreos/xoreos/issues one for xoreos], if the bug concerns the xoreos-tools, use the [https://github.com/xoreos/xoreos-tools/issues one for xoreos-tools]. Likewise, all the other [https://github.com/xoreos 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 [https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow 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 [https://help.github.com/articles/using-pull-requests 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 [https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History 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 [https://git-scm.com/book/en/v2/Git-Branching-Rebasing 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 lists|mailing list]].
== Continuous Integration ==
The public xoreos repositories are build by two [https://en.wikipedia.org/wiki/Continuous_integration Continuous Integration] services on every push: [https://travis-ci.org/ Travis CI] (for GNU/Linux, using both the autotools and the CMake build systems and also using both gcc and clang) and [https://www.appveyor.com/ AppVeyor] (for Windows, using Microsoft Visual Studio). If a compilation error occurs, the build failure announced is on our [https://wiki.xoreos.org/index.php?title=IRC_channel 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.
== Releases ==
A short overview on how xoreos releases work can be found on the [[Releases]] page.


== Reverse engineering help ==
== Reverse engineering help ==
Line 20: Line 70:


* The [http://wiki.scummvm.org/index.php/HOWTO-Reverse_Engineering HOWTO-Reverse Engineering] page in ScummVM's wiki
* The [http://wiki.scummvm.org/index.php/HOWTO-Reverse_Engineering HOWTO-Reverse Engineering] page in ScummVM's wiki
* [http://rewiki.regengedanken.de/wiki/Main_Page REWiki] contains a collection of game reverse engineering knowledge. They have a [http://rewiki.regengedanken.de/wiki/Reverse_engineering_hints hints page] as well
* [https://web.archive.org/web/20180127174342/http://rewiki.regengedanken.de/wiki/Main_Page REWiki] contains a collection of game reverse engineering knowledge. They have a [https://web.archive.org/web/20180117223821/http://rewiki.regengedanken.de/wiki/Reverse_engineering_hints hints page] as well
* [http://wiki.xentax.com/index.php?title=Game_File_Format_Central XentaxWiki] focuses on game file formats. They too have a [http://wiki.xentax.com/index.php?title=DGTEFF guide page]
* [http://wiki.xentax.com/index.php?title=Game_File_Format_Central XentaxWiki] focuses on game file formats. They too have a [http://wiki.xentax.com/index.php?title=DGTEFF guide page]
* For audio and video formats, there's [http://wiki.multimedia.cx/ MultimediaWiki], which is associated with the ffmpeg and libav projects
* For audio and video formats, there's [http://wiki.multimedia.cx/ MultimediaWiki], which is associated with the ffmpeg and libav projects


== Modding communities ==
A lot of information about the file formats can be gleamed from the modding communities:
* [https://neverwintervault.org/ The Neverwinter Vault] for Neverwinter Nights and Neverwinter Nights 2
* [https://nwn.wiki/ Neverwinter Vault Modding Wiki]
* [http://nwn2.wikia.com/wiki/Main_Page NWN2 wiki] for Neverwinter Nights 2
* [https://deadlystream.com/ Deadly Stream] for Knights of the Old Republic and Knights of the Old Republic II
* [http://jadeempire-modding.wikia.com/wiki/Jade_Empire_Modding_Wiki Jade Empire Modding wiki] for Jade Empire
* The [http://www.datoolset.net/wiki/Main_Page Dragon Age Toolset wiki] for Dragon Age: Origins and Dragon Age II
* The [http://witcher.wikia.com/wiki/Category:File_Formats Witcher wiki] for The Witcher
* [http://sonicretro.org/ Sonic Retro] for Sonic Chronicles
* [https://www.nexusmods.com/ Nexus Mods]
* [https://lexicon.nwn.wiki/index.php?title=Main_Page NWN Lexicon]


== To do list ==
== To do list ==


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

Latest revision as of 13:21, 20 July 2022

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, Compiling xoreos-tools and Compiling Phaethon 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 Libera 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.

Releases

A short overview on how xoreos releases work can be found on the Releases page.

Reverse engineering help

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

Modding communities

A lot of information about the file formats can be gleamed from the modding communities:

To do list

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