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:

• hg guide
• coding guidelines

table of contents

mercurial setup

Install mercurial on your system. http:www.selenic.com/mercurial/wiki/index.cgi/BinaryPackages For windows users, TortoiseHg is highly recommended as it includes a gui along with the latest mercurial build.

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

Locate your global config file:

• on windows: C:\Program Files\TortoiseHg\Mercurial.ini
• on *nix: /.hgrc For information on how to edit this configuration file see the man page or the using extensions page.

Download the identities extension identities.py file and save somewhere on your system. (This extension is not yet included with mercurial.)

Setup your global config file to so it contains at a minimum the following:

      [extensions]
      identities = /wherever/you/saved/identities.py

      [identities]
      libqxt = mynick
      ; replace 'mynick' with your chosen nickname

The libqxt project prefers simple one-word nicks as usernames. It is recommended to make this username match your bitbucket username.

A more complete config may include:

      [extensions]
      hgext.graphlog =
      hgext.bookmarks =

      [bookmarks]
      track.current = True

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:

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

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

      $ hg 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. If you are new to hg you may want to read hg guide.

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

• libqxt-tip.zip
• libqxt-tip.gz
• libqxt-tip.bz2

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*
      $ hg pull -u
       *hack*
      $ hg ci
       *hack*
      $ hg ci
      $ hg pull -u
      $ hg 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 ("hg pull -rv0.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

      $ hg branch 0.4
      $ hg up
       *hack*
      $ hg ci

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

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

      $ hg branches
      $ hg branch
      $ hg parents

branches & tags

Be careful with named branches. If you create one, they are forever. After being certain that a new release is near, one dev should announce that they will be creating a new branch. There ways to prune off branches (http://www.selenic.com/mercurial/wiki/index.cgi/PruningDeadBranches) but it would be best if we created them wisely. Tags can be removed a bit easier. A tag will be created at some milestone. To avoid naming conflicts/ambiguity, tags & branches will be named accordingly:

      v0.4.0
      v0.4.1          <== tags
      v0.5.0

      0.2
      0.3             <== branches
      0.4

If you want to work on a particular branch (i.e. a certain version tree that is separated from the default/trunk). Make sure you know where you are, run these commands often:

      $ hg branches
      $ hg branch
      $ hg parent
      $ hg glog

ways to submit contributions

If you are a core developer with write access to the repo, you can simply push back your changes. If not, you will not be able to push your changes back, so we suggest the following ways:

patchbomb

You can submit your patch as a (series of) email(s) to the libqxt-developers list (you must first register). To do this, enable the patchbomb extension included in mercurial and set it up accordingly:

      [extensions]
      hgext.patchbomb =

      [smtp]
      host = my.mail.host.com
      username = joe@blow.com
      password = sekret

If you've made 1 or more commits on your local copy you can do the following:

      $ hg email -r 123 -t libqxt-developers@libqxt.org

         * or if you have more than one revision to share... *

      $ hg email -r 123:126 -t libqxt-developers@libqxt.org

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.

other ways to send in patches

The export command allows you to create patches of your commits and maintains your author info and commit message.

      $ hg export -r 123 > my_amazing_patch

         * or if you have more than one revision to share... *

      $ hg export -r 123:126 > my_amazing_patch

Simply email the patch or pastebin it or otherwise get the patch in the hands of a libqxt developer to review.

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.

This revision is from 2011-11-24 22:17