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.