public
Created

  • Download Gist
gistfile1.rst
reStructuredText

Donations API

TL;DR: Make a standard, decentralised, protocol for developers to define how donations can be given for their apps; integrate this in the Ubuntu Software Centre; make it easy for apps to integrate donations within the app in a standard way.

There should be a standard way for applications or packages to make available information about how to donate.

For Applications

They should put the donation information in their .desktop file under a new section 'Donations'. If this section exists, it should be used for donation information for that application.

The following optional keys could be used:

  • Website - url of a custom donations web page
  • PayPal - paypal email for donations to be sent to
  • Flattr - url of the application's Flattr Thing
  • UbuntuPay - ubuntu single signon email for Ubuntu Pay (via developer.ubuntu.com)
  • GitTip - url of a gittip.com user

For example, Inkscape could have the desktop file:

[Desktop Entry]
Version=1.0
Name=Inkscape
GenericName=Vector Graphics Editor
X-GNOME-FullName=Inkscape Vector Graphics Editor
Comment=Create and edit Scalable Vector Graphics images
Type=Application
Categories=Graphics;VectorGraphics;GTK;
MimeType=image/svg+xml;image/svg+xml-compressed;application/vnd.corel-draw;image/x-eps;application/illustrator;
Exec=inkscape %F
TryExec=inkscape
Terminal=false
StartupNotify=true
Icon=inkscape
X-Ayatana-Desktop-Shortcuts=Drawing
X-Ubuntu-Gettext-Domain=inkscape

[Drawing Shortcut Group]
Name=New Drawing
Exec=inkscape
TargetEnvironment=Unity

[Donations]
Website=http://inkscape.org/donate.php

For Packages

Not everything worth donating to is an app with a .desktop file (eg. command line apps) so there should be a way for any package to define donation information. They should use the same format as with applications but in it's own file located in /usr/share/doc/{package-name}/DONATIONS.

For example, coreutils could have a file /usr/share/doc/coreutils/DONATIONS containing:

[Donations]
Website=https://my.fsf.org/donate/
Flattr=http://flattr.com/thing/313733/gnuproject-on-Flattr

Donation Information Lookup

The following algorithm should be used to find donation information:

#python-like pseudocode
def get_donation_info(app=None, package=None):
    if package:
        if the package provides any .desktop files:
            for each desktop file:
                if it contains a 'Donations' section:
                    return the information in that section
        else:
            if /usr/share/doc/{package-name}/DONATIONS exists:
                if that file contains a 'Donations' section:
                    return the information in that section
    elif app:
        for each dir in XDG_DATA_DIRS:
            if exists dir/{app}.desktop:
                if that file contains a 'Donations' section:
                    return the information in that section

The donate Command

There should be a donate command with the following usage:

``donate`` - launches a GUI listing the apps and packages that allow
    donations and exits immediately.

``donate app=appname`` - launches the GUI at a page for a specific app
    allowing donations (inluding subscriptions if applicable) to be made
    via any of the available methods.

``donate package=packagename`` - launches the GUI at a page for a specific
    package allowing donations (inluding subscriptions if applicable) to be
    made via any of the available methods.

The idea behind this command is so apps can integrate donations via a simple:

system("donate app=myapp");

Integrated Donations

The donate command would allow easy integration of donations in applications. Applications should be advised to make donations available in the following ways:

Via the App Menu

If it is a GUI app with a menu, the donations should be made available through help->donate.

Via GMenu/Menu Buttons

If it is a GUI app that uses a GMenu (the clickable title in GNOME Shell) or a toolbar menu button like in Elementary apps, the donations should be made available as a help item in these manus.

Via the Command Line

The command used to launch the GUI app or use the command line app should have a --donate option that makes donations available.

Ubuntu Software Centre Integration

The Ubuntu Software Centre should integrate this API allowing one off or subscription donations to be made directly from the package's page.

It would also be good to have an option to set up a regular subscription that automatically splits between installed packages that support the API. This means that users could set it up once and forget about it in the knowlege that they will be financially supporting the apps they use. There could be an option to tweak the proportions of this subscription that go to each package.

Please sign in to comment on this gist.

Something went wrong with that request. Please try again.