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.  We have our
own solution for handling Qt things, documented in am/qt.am.

Upstream and Packaging
----------------------

We do not separate 'upstream' code development and packaging for
Debian/Ubuntu/Maemo.  Both happen in the same branch.

In the Maemo context, we don't get any benefit from separating the
two, so we don't.

Thus, all our packages are "native": we do not use Debian revision
dashes such as "0.1-3" in our version numbers, we always use plain
upstream versions such as "0.1".

Documentation
-------------

Documentation is in HTML and generally distributed in the tarballs and
distribution tags.  We do this so that recipients don't need all the
crazy build tools that we use and still get some documentation.

Thus, all documentation files should be added to EXTRA_DIST and
MAINTAINERCLEANFILES.

Since timestamps are not always preserved well enough when checking a
distribution tag out of Git, it might happen that documentation is
being regenerated also during a pure target build, and might fail.

Anyway, you can disable generating of documentation by passing
--disable-doc to configure.

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
   dpkg-buildpackage

 Master should always be buildable by one of the following:

   ./autogen.sh ; ./configure && make
   dpkg-buildpackage

 Running ./autoclean.sh should clean up everything (but not more) that
 was ever generated, so the state should be the same as after the
 checkout.

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

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

 - No tab characters (0x09)
 - Linux style, but
 - Indentation offset is 4 and
 - Maximum line length is 120.
 - No editor specific settings in the files.
 - Code inside a namespace is not indented.

For Python:

 - PEP 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.

The only exception is doc/fig{3,4}.png, they can be generated by dot
(graphviz) from the doc/context-arch.txt, but the generation is
fragile and the font rendering quality depends on the installation.
If you modify the figures, you should delete the fig{3,4}.png, so the
build system will have a chance to regenerate them.  But after this
your version will be committed to the repository, so please double
check that the PNGs are nice and clean.

Distribution 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.

We use debian/changelog instead of ./NEWS.

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 distribution
tags should be buildable with "./configure && make", without running
autogen.sh.

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 distribution 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

  If you don't have any new files not commited yet, you can also use:

  $ git clean -dfx

- Recreate the build cruft.

  $ ./autogen.sh

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

  $ ./configure

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

  $ make
  $ make distcheck

- Make the distribution 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.

Building a debian package
-------------------------

Running 'dpkg-buildpackage -us -uc -rfakeroot -b' to get your shiny
new debian packages should be enough in the case of any distribution
tag, release tag or any commit in the master branch.

The advantage of using a distribution tag (instead of a release tag or
a master commit) is that some of the build-dependencies will not be
needed, since the generated files are already distributed.  Another
advantage is that the build will be a lot faster this way.

So if you can't afford to have some of the tools, you can try a
distribution tag and 'dpkg-buildpackage -us -uc -rfakeroot -b -d',
good luck!

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

Version numbers are bumped post-release: the version numbers in master
and other branches always reflect the version that is going to be
released next.  Once a release has been made, the version numbers in
the branch are immediately incremented.  In addition, version numbers
in branches have a "~unreleased" suffix to make this clear.

Thus, 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.

Thus, as a rule, configure.ac and debian/changelog in a branch should
always have a version number with a "~unreleased" suffix, and the
distribution tags made from a branch should never have a version
number with a "~unreleased" suffix.  Also, no other entry in
debian/changelog than the top-most one in a branch should have the
"~unreleased" suffix.

The procedure for making a release is as follows:

- Make sure that you are in a releasable state.  This includes running
  "make distcheck", running dpkg-buildpackage and checking the
  generated packages for obvious problems, maybe installing those
  packages and doing some smoke tests.

- 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.

- Do the same in debian/changelog, and also make sure that the
  'release notes' in it are up-to-date.

- Update the date line in the top-most entry so that it has your name
  and the current date and time.

- Commit this with a message of "Released VERSION".

- Make a annotated tag with the name "release_VERSION" and the message
  "Released VERSION."

- Run all the steps in "Making a distribution tag".  Use the plain
  VERSION as the tag name.

- Bump the version in configure.ac by increasing the least significant
  component and add the "~unreleased" suffix again.

- Add a new empty entry to debian/changelog with the same version that
  is now in configure.ac.

- Commit this with the message "Prepare VERSION" where VERSION is the
  new version without the "~unreleased" suffix.

- 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.