diff options
Diffstat (limited to 'HACKING')
| -rw-r--r-- | HACKING | 280 |
1 files changed, 0 insertions, 280 deletions
diff --git a/HACKING b/HACKING deleted file mode 100644 index f2cae842..00000000 --- a/HACKING +++ /dev/null @@ -1,280 +0,0 @@ -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. - -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. - - 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. - -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. |