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 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. It's not yet totally clear how to cope with that: one approach is to have something like autotool's "missing", another might be to touch all 'interesting' files just before building. Let's see. Anyway, you can disable generating of documentation by passing --disable-doc to configure. Vala ---- Finding a good vala compiler is hard too, sometimes harder than finding the documentation tools. So we distribute or vala generated C sources too, the same timestamp issues applies, you can disable compilation of .vala files with --disable-vala. 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 distribution tags is not supported in the compilation environment. 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. 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. 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" 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 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 - 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 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 ------------------------- After a git clone, you first have to build vala C sources and documentation. If you have extracted a distribution tarball, then you already have these files. Otherwise just do a ./configure, let's double check that all of the documentation tools and the vala compiler is found and make. After that you are ready to run 'dpkg-buildpackage -us -uc -rfakeroot -b' to get your shiny new debian packages. 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.