Polished HACKING file.

More precise release guide lines, in particular.

1 files changed, 278 insertions, 12 deletions

diff --git a/HACKING b/HACKING
index a6a66da4..9b01c80e 100644
--- a/HACKING
+++ b/HACKING
@@ -1,18 +1,284 @@
-See HACKING in the subsys-context-doc package for general coding guide
-lines.
+How to hack on the ContextKit
+=============================
 
-There are some ContextKit specific additions:
+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.
 
-- Packaging is done in the "pkg-master" branch, "master" is kept free
-  from packaging bits.
+Build system
+------------
 
-  You should merge "master" into "pkg-master" from time to time.
-  Never merge "pkg-master" into "master".  If you want to move changes
-  from "pkg-master" back to "master", cherry-pick them.
+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.
 
-- Package releases are also made from "pkg-master", of course.
+Packaging
+---------
 
-  Merge "master" into "pkg-master" and test, fixing any package
-  related things.
+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.
 
-  Then make a release tag as explained in subsys-context-doc/HACKING.
+"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.