Notes for contributing to the Zeitgeist engine

Coding style

In general, follow PEP 8 <http://www.python.org/dev/peps/pep-0008/>. Especially try to keep the lines shorter than 80 characters. We are also using TAB for indention.

Zeitgeist supports Python 2.6 and later.

Testing

Before each commit to lp:zeitgeist the commiter must make sure that our testsuite in test/ is running successfully. Easiest way to run our testsuite is make check. We aim to get as much code tested as possible. New features and bug fixes should get doc or unittests.

Documentation

Our public API (code in zeitgeist/) must be fully documented. Code in _zeitgeist/ is private code and should be documented and written in a way so that others can understand it.

Changes to the public (DBus) API

changes to the public API are only possible in a major release series.

Code Review

We are using launchpad’s ‘merge proposal’ feature for our code review process. Significant changes must have at least one positive vote from one of the core developers (members of <http://launchpad.net/~zeitgeist>)

Release Tasks

0. Ensure the translations are up-to-date. You may find daily translation exports provided by Launchpad at lp:~rainct/zeitgeist/translations.
1. Bump version number to $VERSION in configure.ac and VERSION files, and the D-Bus API version in _zeitgeist/engine/remote.py, if there have been changes to it. Also make sure to bump the ‘version’ and ‘release’ variable in doc/zeitgeist/source/conf.py to something sensible (e.g. $VERSION)
2. Update NEWS file by hand

(hint: you can see the full change log with ‘bzr log -n0 -v | less’,

to get a log of all changes after the last release run ‘bzr log -n0 -v -r tag:bzr tags –sort=time|awk ‘END{print $1}’..|less’)

3. Commit your changes (with only these changes!) and push you current branch to lp:zeitgeist and lp:~zeitgeist/zeitgeist/zeitgeist-$VERSION Before pushing make sure there is a $VERSION tag for the ‘release’ revision, to create one run ‘bzr tag $VERSION’.

4. To make sure you have a pristine source tree do a clean checkout of the newly created branch:

   bzr branch lp:~zeitgeist/zeitgeist/zeitgeist-$VERSION

5. Change working dir to your new branch

6. Run ‘./autogen.sh && make && make distcheck’. Unpack the tarball and generate it again with “tar -czvf zeitgeist-$VERSION.tar.gz zeitgeist-$VERSION” (distcheck’s are bigger and may be corrupt).

7. GPG sign the generated tarball with the command:

   gpg –armor –sign –detach-sig zeitgeist-$VERSION.tar.gz

8. Upload the tarball and the generated *.asc GPG signature to the right milestone on Launchpad

9. Send announcement email to the mailing lists:

   • zeitgeist@lists.launchpad.net
   • dev@lists.zeitgeist-project.com
   • gnome-zeitgeist-users@lists.launchpad.net
   • gnome-announce-list@gnome.org

10. Post a news update on the Launchpad project page based on your announcement email

11. Make sure that the API documentation on zeitgeist-project.com is updated

12. Now you deserve a treat!

Bugs

The Zeitgeist project is using the bugtracker on launchpad.net. To report a bug please visit https://bugs.launchpad.net/zeitgeist/+filebug and describe the issues you are having. Please also add useful information like the version of Zeitgeist you are using and the Python version.

Apart from classical bug reports describing an issue or failure, the Zeitgeist team is using the bugtracker to discuss new features and implementation details.

Bug triaging

The Zeitgeist project is using bug status as described below:

• New: no bug triager had a look at this bugreport
• Incomplete: the zeitgeist team has asked an explicit question to get a better understanding of the bug and is waiting for an answer from the original reporter or anyone having the same issue
• Invalid: It turned out that the issue is not a bug in zeitgeist, or cannot be fixed in zeitgeist.
• Won’t Fix: based on the information we got on the bugreport we decided that we don’t want to fix this bug in a reasonable timeframe.
• Triaged: Based on the information in the bugreport zeitgeist developers understand the issue and are able to start fixing it.
• In Progress: Someone is working on a fix. There should be a branch attached to the bugreport, and the zeitgeist task should be assigned to the developer who is working on the fix.
• Fix Committed: The fix for this bug has been merged into lp:zeitgeist. When setting this status the triager should add information about the revision in which the fix landed, and also ask the reporter and other affected user to test the fix.
• Fix Released: The fix was released in a release of zeitgeist.

The ‘Opinion’ status is not used by zeitgeist.

The importance of a bug is set by following this criterias:

• Undecided: No decission has been made.
• Wishlist: we are marking feature requests as wishlist
• Low: issues affecting only a small number of users are marked as Low
• Medium: bugs which are affecting a significantly number of users are of medium importance.
• High: This class of bugs must be fixed before the next release, esp. failures of our testsuite are resulting in bugs which are marked as ‘High’. Also different kind of regressions (crashes, performance etc.) are marked with this importance.
• Critical: Used when a bug causes Zeitgeist to generally not work at all for a large user base. This could be build failures, frequent crashes, or loss of key parts of the functionality.

Milestones:

• If we plan to fix a bug with a status of ‘Wishlist’, ‘Low’ or ‘Medium’ we should target this bug to a milestone
• ‘High’ and ‘Critical’ rated bugs will always be targeted to the next milestone.

Related policies:

• Every bug of status ‘Triaged’ or higher should have an importance other than ‘Undecided’.
• Each bug with status higher than ‘In Progress’ should get an assignee. Assigning a bug to a dev should never be done without talking to him/her.

Blueprints

Blueprints are used in the zeitgeist project to describe a development story. Whenever a certain feature requires fixes for multiple bugs or multiple branches to be merged we use blueprints to organize the efforts under one central umbrella. The assignee of a blueprint is leading all the work to get this blueprint and all its features/fixes implemented.