Hacking PackageKit

Coding Style
------------
The tree is auto-formatted. Before submitting, run:

	$> ./autoformat.py

This formats C and C++ with clang-format and Python with black, following
the rules in .clang-format. The C++ backends carry their own .clang-format,
which the script picks up automatically.

To check without changing anything, or to format only what you touched:

	$> ./autoformat.py --check
	$> ./autoformat.py src/pk-engine.c lib/

Tabs are hard (not expanded to spaces) and 8 wide, and trailing whitespace
is removed for you, so the C ends up looking like this:

	/* map the roles to policykit rules */
	if (role == PK_ROLE_ENUM_UPDATE_PACKAGES ||
	    role == PK_ROLE_ENUM_UPDATE_SYSTEM) {
		policy = "org.freedesktop.packagekit.update";
	} else if (role == PK_ROLE_ENUM_REMOVE_PACKAGE) {
		policy = "org.freedesktop.packagekit.remove";
	}

A few things the formatter cannot decide for you:

* All documentation and code should be in US English.

* Please DO NOT use "!" for a null pointer check.

* Tables whose columns carry meaning -- the enum-to-string maps in
  lib/pk-enum.c, the GOptionEntry tables -- are wrapped in
  /* clang-format off */ ... /* clang-format on */, because clang-format
  would put every field on a line of its own. Keep new ones that way.

* A TRANSLATORS comment has to sit on the line directly above the call it
  describes:

	g_print ("%s\n",
		 /* TRANSLATORS: the user did not provide a package name */
		 _("A package name is required"));

  xgettext only picks it up from there. If reformatting moves the string
  onto a line of its own, move the comment down with it.

Functions are nearly always the same format, gtk-doc is optional:

/**
 * pk_engine_search_name:
 **/
gboolean
pk_engine_search_name (PkEngine *engine, const gchar *search, GError **error)
{
	gboolean ret;
	PkTransactionItem *item;

	g_return_val_if_fail (engine != NULL, FALSE);
	g_return_val_if_fail (PK_IS_ENGINE (engine), FALSE);

	return TRUE;
}

Security
--------
Remember:
* The daemon is running as the root user
 - no FIXME or TODO code please
* If the daemon crashes, then that's a DOS
* Text from the user (over the dbus interface) is insecure!
 - even filters and enumerated values can be wrong
 - users can use dbus-send to do bad stuff as users
* Never allocate a buffer on user input
* Output from backends is trusted, they are run from standard locations

Submitting Patches
------------------
We prefer patches submitted as pull requests to our GitHub project at
https://github.com/PackageKit/PackageKit

However, if you are unable to use GitHub, you can also submit patches
via email.

To do so, Use 'git format-patch' to generate patches against a checked
out copy of the source.

For example:

	$> cd PackageKit
	HACK HACK HACK
	$> git commit -m "My first commit"
	HACK HACK HACK
	$> git commit -m "My second commit"
	$> git format-patch -M HEAD^^
	0001-My-first-commit.patch
	0002-My-second-commit.patch

Send these patches in an introductory email as attachments to
packagekit@lists.freedesktop.org

Commit/Patch Style
------------------
Commits (and thus patches) should be structured such that each one
is a logically distinct change that stands well and can be tested
on its own.

Commit/Patch messages should be wrapped at 72 characters, and the
subject line (minus the subsystem prefix) should be less than 50
characters.

What we mean by subsystem prefix is the portion of the codebase
that is being modified.

For example, if you are changing something in the main library,
use "lib:" as the prefix of the patch subject. If you are
changing something in one of the backends, use the backend name
as the prefix in the patch subject.

There are a number of examples of this already in the revision
history, so look at any number of them for good examples.

Finally, please do not use commit messages as a means for
advertising. The revision history is not a place for rent-free
permanent advertising. It can be especially problematic as
sponsoring entities change, rename, or such.  That means that
tags like "Sponsored-by" or similar are not allowed.
