libqxt developer guide

This is meant as a guide to get you started with developing qxt. If, after reading this guide, you have questions, please see us on #qxt on freenode and we will be glad to help. Other pages that may be useful:

coding guidelines

table of contents

libqxt developer guide

git setup

Install git on your system. For windows users, TortoiseGit or MsysGit

After installing there are some essential steps to properly setup your mercurial environment.

    $ git config --global user.name "John Doe"
    $ git config --global user.email "John.Doe@example.com"

It is recommended to make the mail address match your bitbucket mail.

Since git checks in line endings as your editor writes them, either make sure to use unix line endings everywhere, or set

    $ git config --global core.autocrlf true

to automatically convert line endings for you.

starting development

The easiest way to start developing with the libqxt library is to create an account on bitbucket. Once you have done this, add your public ssh key to your bitbucket account to allow for password-less pushing/pulling from the repo. If not, you will need to supply a username/password at the prompt on every operation.

Get your own copy of the repo:

      $ git clone ssh://git@bitbucket.org/libqxt/libqxt.git

         * or if you don't have your ssh key setup... *

      $ git clone https://<myusername>@bitbucket.org/libqxt/libqxt/

This will create a fresh copy of the repo in ./libqxt. You are now ready to start hacking on qxt code.

You can also get a copy of repo without a bitbucket account by just downloading one of these:

typical workflow

This assumes you are a core developer and have write access to the repo. If you are not there are other ways for you contribute back your changes.. see 'ways to submit contributions' below.

Please pull and update before you start hacking, this will help avoid unneeded merges later. After completing your task, pull and update again and perform any merging necessary before pushing back to the repository.

       *think of something to implement*
      $ git pull --rebase
       *hack on bla.cpp"
      $ git add bla.cpp
      $ git commit
       *hack more*
      $ git add bla.cpp
      $ git commit --amend
      $ git pull --rebase
      $ git push

libqxt repo structure

The libqxt project uses "named branches" and "tags" to designate version trees and version revisions. Most development happens in the 'default' branch (analagous to 'trunk' in svn) and this is most likely where you will be working if you contribute to the project. When a feature freeze occurs, and we are near a release, we will create a new branch for that release line, for instance for the upcoming 0.6.0 release, we will create a 0.6 branch. This allows us to continue to work on new developments for future releases in the default branch. Shortly after the 0.6 branch is created (perhaps immediately after) we will tag a specific revision as "v0.6.0" and this will be a permanent tag that you can always use to get that version ("git checkout v0.6.0"). This branch will be used to provide bug fixes etc, but probably will not include new features being introduced into the default branch.

If you want to work on a particular version branch do the following

      $ git checkout v0.6.0

For more on branches and tags: http://hgbook.red-bean.com/hgbookch8.html

Make sure you know what branch you're on!!

      $ git branch
      $ git branch -a

requesting a pull from your own repo

A cool feature of bitbucket is that you can easily make a fork of the libqxt repo under your own control, just click the fork link on http://bitbucket.org/libqxt/libqxt/. You can then clone that repo onto your own pc, do your work there, and push changes back to your repo anytime you want.

When you have something you'd like to share you can request for libqxt to pull your changes into its own repo by clicking the 'pull request' link on your own repo page.

useful commit messages

Always try to make your commit descriptions as verbose as needed but no more than needed. The first line of your description should sum up all of the work you did. Use additional lines for implementation details (if necessary) and other metadata.

An example commmit message which fixes bug #4711 in the issue tracker where the QxtLabel displays text in the wrong orientation:

      fixed orientation issue in QxtLabel
      had to fix some code in paintEvent()
      also added a convenience function orientation() that cleans up some of the code
      fixes #4711

Use fixes issue_id whenever resolving an issue, or refs issue_id whenever you want your commit to appear in the issue tracker as a comment. See the bitbucket issues service for more info.

Wiki

libqxt / libqxt_developer_guide