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.