~libqtelegram-team/telegram-app/telegram-app-dev

# Hacking on Telegram for Ubuntu

##Pre-requisites

These instructions have been tested on:

    1. Ubuntu 14.04 (Trusty Tahr)
    2. Ubuntu 14.10 (Utopic Unicorn)

Ensure you have the Ubuntu SDK installed, as per:
    http://developer.ubuntu.com/start/ubuntu-sdk/installing-the-sdk/

Ensure you have bazaar installed and configured to branch from/push to Launchpad.

## Source

These are the important branches:

* lp:libqtelegram

the trunk of the libqtelegram library

* lp:libqtelegram/dev

the devel branch of the libqtelegram library

* lp:libqtelegram/app

the trunk of the Telegram app

* lp:libqtelegram/app-dev

the devel branch of the Telegram app

Propose Telegram application merges to this branch:

* lp:libqtelegram/app-dev

Propose libqtelegram library merges to this branch:

* lp:libqtelegram/dev

More or less on the weekly basis, we land the devel branches to trunks.

Building in the IDE is not fully supported, but you can try.

 * be sure to import CMakeLists.txt
 * add -DCLICK_MODE=on as a cmake command line arg

Debugging
=========
Telegram will log debug output on the phone to:

    /home/phablet/.cache/upstart/

The file name will resemble:

    application-click-com.ubuntu.telegram_telegram_1.0.0.89.log

But will change depending on the version number.

It is easiest to get the live log feed with:

    ./scripts/app-log.sh

Another common error may be AppArmor denials. To view those:

    grep DENIED /var/log/syslog | grep telegram

If Telegram crashes, it will create crash files similar to:

    /var/crash/_usr_lib_arm-linux-gnueabihf_qt5_bin_qmlscene.32011.crash

If there are also files named *.upload and *.uploaded, it means that the
Ubuntu system error logger (named ``whoopsie``) has uploaded them to

    https://errors.ubuntu.com/

You must login to the page using your Ubuntu SSO credentials. Then you can
find your crash's stack trace by navigating to:

    https://errors.ubuntu.com/oops/<OOPS-ID>

To find the OOP-ID, view:

    /var/crash/upstart/whoopsie.log

And search for a line that resembles:

    Reported OOPS ID 4923130e-1879-11e4-ab04-fa163e339c81

The long hex string should be entered into the URL above (without the angle
brackets).

If whoopsie did not upload the crash to the Ubuntu error tracker, you can
still analyze the crash locally. Use ``adb pull`` to copy the *.crash file
onto your development machine. Then:

    sudo apt-get install apport-retrace
    apport-cli <name of crash file>

You can then follow the menu options to 'V'iew the trace locally. The other
option is to install ``apport-retrace`` on your device itself, and directly
issue:

    apport-retrace <name of crash file>

Finally, please file all bugs to:

    https://bugs.launchpad.net/libqtelegram

##Building (armhf)

###Stable

    bzr branch lp:libqtelegram/app
    cd app

We now need to:

 1. ensure we have the armhf click chroot created
 2. the click chroot is up to date and has required dependencies installed
 3. get the Telegram plugin from launchpad

Run this once:

    ./bootstrap update

Now that you're done with the set-up, you can build Telegram for Ubuntu simply with:

    ./click.sh

Or, you can run this to also install the click onto a hooked-up (and screen unlocked!) device:

    ./click.sh install

This is actually a simple convenience wrapper around click-buddy.

###Devel

Steps are similar as above, however the UI part and the plugin part are hosted in different branches:

    bzr branch lp:libqtelegram/app-dev
    cd app-dev
    TG_PLUGIN=lp:libqtelegram/dev ./bootstrap.sh
    ./click.sh [install]

##Proposing a patch to app UI

    bzr branch lp:libqtelegram/app-dev
    cd app-dev

Optionally, if you want to build to test your changes, you'll need the plugin:

    TG_PLUGIN=lp:libqtelegram/dev ./bootstrap.sh

Now, hack, hack, hack!

If you've ran click.sh in the mean time, clean-up translations before proposing changes
to avoid noise in the merge diff:

    bzr revert po/com.ubuntu.telegram.pot

We'll let launchpad do it automatically, or when we land changes to trunk.

    bzr add (if you intend to add new files)
    bzr commit -m "Message explaining what this branch does. Say, add secret chat feature."
    bzr push lp:~your_name/libqtelegram/app-dev-YOUR_BRANCH_NAME

If you are a member of libqtelegram-team, please push like this instead:

    bzr push lp:~libqtelegram-team/libqtelegram/app-dev-YOUR_BRANCH_NAME

This way, other team members can pick up where you left and fix any problems while you're away.

Please use meaningful branch names and commit messages. "Fix 1234567" tells us nothing.
If the branch fixes a bug, please commit like so instead:

    bzr commit --fixes lp:xxx -m "..."

where xxx is the bug number on Launchpad that this branch fixes.

Now open the branch up in launchpad, and propose a merge against lp:libqtelegram/app-dev
Thank you for your contribution! We'll take it from there and provide feedback.

## Proposing a patch to app plugin

Steps are virtually same as above, but you focus on the library directory.

    bzr branch lp:libqtelegram/app-dev
    cd app-dev
    TG_PLUGIN=lp:libqtelegram/dev ./bootstrap.sh
    cd library

Now, hack, hack, hack!

    bzr add (if you intend to add new files)
    bzr commit -m "Message explaining what this branch does. Say, add secret chat feature to the plugin."
    bzr push lp:~your_name/libqtelegram/dev-YOUR_BRANCH_NAME

Similarily as above, please use ~libqtelegram-team, if you're a team member.

Now open the branch in launchpad, and propose a merge against lp:libqtelegram/dev
Thank you for your contribution! We'll take it from there and provide feedback.

## Bumping Telegram version (required in following section)

Telegram for Ubuntu uses MAJOR.MINOR.PATCH.REVISION for versioning.

REVISION is always current branch revision, and is added automatically.

MAJOR.MINOR.PATCH is more or less http://semver.org/ , meaning:

 * MAJOR bump indicates major milestones / non-backward compatible releases
 * MINOR bump indidates new features (backward compatible)
 * PATCH bump indicates new bugfixes (backward compatible)

Here's the pro-tip:

 * Stable (trunk) uses even numbers for patch.
 * Devel uses odd numbers for patch.

So, by looking at 0.9.7.82 you see (by 7) it's a devel/daily build, revision 82.
In 1.0.2.88 you see (by 2) it's a trunk build, revision 88.

When landing feature branches to lp:libqtelegram/app-dev and lp:libqtelegram/dev,
if those changes go in pair (UI depends on plugin and/or vice versa), you should
look at the last tags of both branches (usually app-dev would have higher), and
bump it accordingly.

Example:

    app-dev is at 0.1.3.3
    dev is at 0.1.0.1

You add a single feature (related to both branches) to them, so you:

    bzr tag app-dev 0.1.5
    bzr tag dev 0.1.5

This way, the team can see these branches have to be landed together as they're related.

## Landing devel in trunk

** Following can be done by Canonical staff only **

Make sure you have a clean slate, this has to be done with extra care.
You can start in /tmp if you like, or an empty directory.

First, review libqtelegram project for any branches that may have been left for merging.

If you want, you can branch the devel branches and conveniently inspect history with bzr qlog (in bzr-tools package) to see latest changes and make sure what you're about to land is, in fact, already properly present in devel branches.

Branch UI trunk.

    bzr branch lp:libqtelegram/app
    cd app

Branch plugin trunk.

    ./bootstrap.sh

Merge dev UI, don't commit yet.

    bzr merge lp:libqtelegram/app-dev

Merge dev plugin, and commit that.

    cd library
    bzr merge lp:libqtelegram/dev
    bzr commit -m "Merge dev branch."
    cd ..

Now build the click for the translation files to be updated.
The version will be broken in click name, ignore that, we'll tag it AFTER we commit.

    ./click.sh

Now you're ready to commit the changes.

    bzr commit -m "Merge dev branch."

Now bump the version accordingly (without the REVISION part), x.y.z is just a placeholder here.

    bzr tag x.y.z
    cd library
    bzr tag x.y.z (same as above)

Now that's done, you can build the thing ;)

    ./click.sh [install]

It will have proper version string, including the bzr revno.

## Hand over to QA

Once Telegram is built from trunk, it is uploaded to GoogleDrive directory:
[...] > Telegram > Releases > click

Then, a new copy of release notes (in the Releases folder) needs to be created and filled out.
Then, a new sheet in the 'Telegram: release check list' needs to be created (first sheet is the template) and filled out.
At this point, we send an e-mail to one of our QA engineers (usually joc) with such title or similar:

    Telegram y.y.z.r for QA (M16)

where M16 is an example milestone name.
We include:

- the milestone link
- the release notes link
- the checklist sheet link

and wait for the results.

## Publishing

Ping karni (instructions available on internal wiki).

## Tips

    TG_PLUGIN=lp:foo ./bootstrap.sh

is an alias for 

    bzr branch lp:foo library

However, bootstrap.sh ensures the click chroot is created, and allows you
to update it as well as install Telegram build dependencies.