-
Notifications
You must be signed in to change notification settings - Fork 1
Contributing to Tiled
If you already know a bit of C++, contributing to the Qt version of Tiled is not hard! All you need to do is learn how to use the Git version control system and the Qt application framework. But you can do either as you go along.
Installing Git is going to be a bit different depending on your operating system. If you go to the Git download page, you should be able to find the appropriate link (for Windows I'd recommend the msysGit version over Cygwin).
While you can use the Git gui to check out the repository, I'm only going to show you the way of the command line here. The Git repository is located here on github.com. You'll find Tiled at http://github.com/bjorn/tiled.
To make a local copy of this repository, use the command advertised there:
$ git clone git://github.com/bjorn/tiled.git
$ cd tiled
$ git log
As the last command shows, this not only gives you a local copy of the source code, but also includes all the development history, allowing you to browse the history quickly and find out what happened until now.
Now, to compile this project you'll need a compiler set up and the Qt development libraries installed. An easy to use development environment would also be nice. The Qt SDK combines all these things (though on Linux and Mac, you'll have to install the compiler yourself). If you already have the Qt development libraries installed (or prefer to install those of your favourite Linux distribution), you can also get just the Qt Creator IDE (links at the bottom).
Apart from the Qt SDK, Tiled also depends directly on zlib for supporting compression. On Debian and Ubuntu, zlib can be installed as follows:
$ sudo apt-get install zlib1g-dev
Once you have a compiler, the Qt development libraries installed and Qt Creator installed, you should be able to just open tiled.pro in Qt Creator. You can then press the Run button to have it compile and run the application.
If you don't like IDEs and prefer to stick with the command line and, quite possibly, vim, you'll find that you can compile and run Tiled using the following commands:
$ qmake # Generate the Makefiles
$ make # Compile Tiled
$ bin/tiled # Run Tiled
Note that Tiled Qt uses Qt 4. If you have both Qt 3 and Qt 4 installed, the qmake command may default to Qt 3. In this case, use "qmake-qt4" (or the command on your system relevant to qt4) instead of qmake.
Edit the code using your favourite editor. While you're at it, always feel free to ask questions on the mailing list or on the IRC channel, see the relevant links on the website.
Once you think your change is ready, you need to create a commit. Before you create your first commit, you should tell Git who you are. You can do so as follows:
$ git config --global user.name "Real Name Surname"
$ git config --global user.email "your.email@domain"
This information is stored with each commit you make, and makes sure we all know who the author of the change was later on. Note that Git does not have a concept of user accounts, as is common in centralized version control systems like Subversion.
Now, before you commit, it is generally a good idea to look at the output of git status. This might look something like this:
[bjorn@thor tiled-qt]$ git status
# On branch master
# Changed but not updated:
# (use "git add <file>..." to update what will be committed)
# (use "git checkout -- <file>..." to discard changes in working directory)
#
# modified: src/mapscene.cpp
# modified: src/src.pro
#
# Untracked files:
# (use "git add <file>..." to include in what will be committed)
#
# src/smartbrush.cpp
# src/smartbrush.h
Here, Git says that you have modified the files mapscene.cpp and src.pro, and introduced two new files unknown to git (smartbrush.cpp and smartbrush.h). To commit these changes, you would do:
$ git add src/mapscene.cpp
$ git add src/src.pro
$ git add src/smartbrush.cpp
$ git add src/smartbrush.h
$ git commit
[write commit message in editor that was started]
Note that in this case, you could also have done this instead of adding all files individually:
$ git add -A
However, this is a bit dangereous, since it adds all files unknown to git, which may include files you don't want to add to version control. Read the output of git status carefully before doing something like that. A safer way would have been:
$ git add src/smartbrush.{cpp,h}
$ git commit -a
Here, the second line tells Git to add all changes to already tracked files to the commit. I find the easiest way to create a commit, however, to be git gui. This allows you to interactively select the parts you want to be part of your commit, review those changes before you commit, and to write your commit message.
There's many ways to do this. If you are unsure about your change, have somebody review it. Export your commits using:
$ git format-patch origin/master
Then, send the file to the mailing list or show it to somebody on IRC. If you want to contribute to the project longer term, you may prefer to create a fork of the Tiled repository on github.com, and push changes there. That allows you to do "pull requests" via the website, and it allows everybody to see what you are changing in Tiled in general.
When your patch is good for inclusion, it will be pushed to the main repository. When updating your local repository, make sure your local changes are rebased on top of the remote ones, by pulling as follows:
$ git pull --rebase
This ensures that accepted commits are dropped, and no unnecessary merge commits are created for commits which haven't been accepted yet.
Happy coding!