path: root/HACKING

How to hack on the ContextKit
=============================

These are the coding and release guidelines for the ContextKit.  They
are quite general, so if you like them, feel free to copy them into
your project.

Build system
------------

We use the autotools in their 'foreign' strictness plus pkg-config.
We don't use qmake, even for Qt programs or libraries.  Use pkg-config
when you use Qt libraries and write explicit rules for invocations of
tools like moc.  See the ContextCommander for an elaborate example.

Packaging
---------

We separate 'upstream' code development and packaging for Maemo into
separate branches.  Upstream development generally happens on the
"master" branch, and packaging on the "pkg-master" branch.

"Master" is merged into "pkg-master" at controlled points in time.
(See below "Making a release" for more details.)  Never merge
"pkg-master" into "master".  If you want to move changes from
"pkg-master" back to "master", cherry-pick them.

Environments
------------

Our code should be as portable as possible, but a few environments are
more important than others.

There are supported development environments, and compilation
environments.

 - Development

 For fun and fame, our code should work in a typical Debian unstable
 and Ubuntu environment, augmented with our own packages that we build
 from source.  (If it works in Fedora, too, cool!)  This is our
 day-to-day development environment.

 The projects only need to work fully when installed.  Thus, the
 projects must be cleanly installable in arbitrary prefixes.  The
 following should work to install everything in $HOME/install:

   ./configure --prefix $HOME/install/
   make install

 The installed projects should then fully work with these settings:

   PATH=$HOME/install/bin/
   LD_LIBRARY_PATH=$HOME/install/lib/
   PKG_CONFIG_PATH=$HOME/install/lib/pkgconfig/

 The "master" branches on the mainline repos on PMO should always pass
 "make check" in the development environments, after doing the
 necessary autogen.sh gymnastics in a fresh checkout.

 For projects that can not be developed in Debian or Ubunute, do
 whatever needs to be done.  Document this in a "HACKING" file in the
 top directory of the source tree.

 However, try to port the project to Debian/Ubuntu instead, maybe by
 making certain features optional or by importing the missing dependencies.

 - Compilation

 For pain and profit, the code also needs to compile in a Harmattan
 target in Scratchbox.  We only use Scratchbox 1 for now, with the
 following devkits: perl, debian-etch, doctools.

 When in doubt, follow these instructions to set it up:

    https://projects.maemo.org/trac/sdk/wiki/Harmattan

 Distribution tags (see below) should be buildable with one of these
 two commands right after checking them out

   ./configure && make     (for a upstream source tree)
   dpkg-buildpackage       (for Debianized sources)

 Note that things like running ./autogen.sh or more generally
 regenerating files that are contained in release tags is not
 supported in the compilation environment.

Coding style
------------

We follow the DUI coding style for C++ code.  In brief:

 - Linux style, but
 - Indentation offset is 4 and
 - Maximum line length is 120.

For Python:

 - PEP 8, but
 - Maximum line length is 120.

For Vala:

 - Linux style with indentation offset 8, but
 - Maximum line length is 120.

Generated files
---------------

No generated file should be committed to a branch.  After checking out
(or exporting) a branch, running "./autogen.sh" will get the tree into
a shape where "./configure && make" or "dpkg-buildpackage" will work.

Release tags are different, see below.

ChangeLogs
----------

There is no GNU-style ChangeLog.  We assume that the VCS keeps a
detailed log of the changes.  Likewise, debian/changelog does not
record detailed changes, just the stuff that would go into an
announcement.

There is generally no NEWS file; the debian/changelog is used in its
place.  Thus, debian/changelog talks about user visible changes to the
whole source tree, not just the packaging bits.

Marking fixed bugs
------------------

When committing a change that is supposed to fix a bug, make a
annotated tag for it with the name "fixes_NNNNN" where NNNNN is the
Bugzilla bug number.  Use the message "Fixes: NB#NNNNN - SUMMARY"
where SUMMARY is of course the one-line summary of the bug.

(The annotation message is there to carry the summary.  Bugzilla is
not visible to the outside, and we should give some hints about what
kind of bugs we have fixed.  With a public Bugzilla, a simple
leightweight tag would suffice.)

Making a distribution tag
-------------------------

No generated file should be committed to a branch, but release tags
should be buildable with "./configure && make" or "dpkg-buildpackage"
right away after exporting them, without the need to run autogen.sh.
The created Debian source package should be clean, and not contain any
files that are not supposed to be distributed.

In general, a tag should contain exactly the files that would be in a
distribution tarball produced by "make dist".  In essence, we use tags
in a VCS repository instead of the traditional tarballs.

Note that release tags are usually created in the development
environment, outside of Scratchbox.

Here is the general procedure:

- Clean everything that can be generated.

  $ make maintainer-clean || make distclean

- Recreate the build cruft.

  $ ./autogen.sh

- Configure your source tree as needed for making a release.

  $ ./configure --enable-maintainer-mode --enable-gtk-doc

- Build the source tree and do a "make distcheck"

  $ make
  $ make distcheck

- Make the release tag with git-make-dist (in the tools/ directory).

  $ git-make-dist TAG

The "git-make-dist" script runs "make distdir" and creates a tag with
the contents of the created directory.

Making releases
---------------

Version numbers are bumped post-release: configure.ac always contains
the version that is going to be released next with a "~unreleased"
suffix and debian/changelog contains a prepared entry for the next
release with a "~unreleased" suffix.

That suffix is there to make it clear that we are using the
"post-release bump" schema.  It also reduces confusion when you create
a tarball or Debian package from a branch for testing purposes.  Those
tarballs and packages will be clearly marked to be 'unreleased', and
can not be confused with the real releases.  Do not distribute these
unreleased packages to other people.

If you do want to label multiple intermediate non-releases, use
suffixes of the form "~unreleasedN".  Do this by changing the existing
debian/changelog entry in place.  Do not create a new entry.

As a rule, configure.ac in a upstream branch should always have a
version number with a "~unreleased" suffix.  The release tags made
from a branch should never have a version number with a "~unreleased"
suffix.

Likewise, the topmost entry of the debian/changelog in a branch should
always have a "~unreleased" suffix, and no other entry should have
such a suffix.  A debian/changelog file in a release tag should not
have a ~unreleased suffix.

Also, the configure.ac file in a packaging branch should _not_ have a
"~unreleased" suffix.  In other words, only merge the
"release_VERSION" tags into a packaging branch.  Never merge the
upstream branch itself between releases.

If you want to merge the upstream branch with the packaging branch for
experimenting, make a new branch for this purpose.  The continous
integration machinery creates such a throw-away branch whenever
"master" changes, with the name "pkg-next".

** Upstream releases

When making the release in a upstream branch (a branch without the
packaging bits), remove the "~unreleased" suffix in configure.ac.  You
can also increase the version more generally at this time, such as
from 0.1.5~unreleased to 0.2.0.

Then do all the steps listed in "Making a release tag" *except*
running git-make-dist.  Once the final "make distcheck" succeeds,
commit the removal of the "~unreleased" suffix with the commit message
"Released VERSION."  (VERSION is of course the version in configure.ac
without the ~unreleased suffix.)

Then make a annotated tag with the name "release_VERSION" and the
message "Released VERSION."

Then run all the steps in "Making a release tag" again, this time
*including* git-make-dist.  Use the plain VERSION as the tag name.

Then bump the version in configure.ac to by increasing the least
significant component and add the "~unreleased" suffix again.

Push everything.  Don't forget to push the tags as well.  If you can't
push at this time because you need to pull first, do that but be
careful to merge the remote changes.  Do not use "git pull -rebase" at
this time.

** Merging a upstream release into a packaging branch.

Merge the most recent "release_VERSION" tag into the packaging branch.
Update the topmost debian/changelog entry (which has the ~unreleased
suffix) to have version VERSION-1~unreleased, adding the text "New
upstream release." and a summary of the changes compared to the last
upstream release.

Look for tags of the form "fixes_NNNNN" and copy their messages into
debian/changelog.  [ This should be automated. ]

** Package releases

Making a release on a packaging branch is very similar to releasing a
upstream branch.

The only differences are:

 - You leave configure.ac alone, which shouldn't have any ~unreleased
   suffix if you have followed the rule about only merging
   release_VERSION tags into a packaging branch.  Instead, you remove
   the ~unreleased suffix in debian/changelog.

 - Instead of using "release_VERSION" for the tag, you use
   "pkg_VERSION-REVISION".

 - You use "VERSION-REVISION" for the distribution tag name.
   Git-make-dist will automatically include the debian/ directory in
   the distribution tag.

Snapshots versus releases
-------------------------

We make a 'real' release as explained above whenever we need to
integrate something.  Such a release gets a real version number, and
not a timestamp suffix or similar.