Next: , Previous:  Packaging GNU Makefile for desklets, Up: Top


Appendix F Submitting a desklet

F.1 Desklet package requirements

Requirements for “official” desklets packages are scarce; authors are free to do as they wish. There are only two things that should be enforced:

  1. A meaningful README file should exist in the base source directory of the desklet archive and be kept up to date. It should at least contain:
    • the name and contact email adress of the author1
    • a short description of the desklet
    • the requirements for running it
    • how to run it
  2. The package should be a bzip'ed tarball containing a single source directory of the form NAME-MAJOR.MINOR.REVISION, where NAME is the desklet base name, and MAJOR.MINOR.REVISION the version. Please note that a makefile (See Packaging GNU Makefile for desklets.) is also provided to automate creation of such an archive on GNU systems.

F.2 The adesklets_submit script

Starting in adesklets 0.4.4, desklet authors are provided with a Python script to automate the submission of their desklets: utils/adesklets_submit from the source package. Use the --with-python-install-submission-scripts option at configuration time to place it in your bindir directory upon installation.

adesklets_submit can be used to:

F.3 Invoking adesklets_submit

Desklet submission is initiated by sending a specially crafted email to adesklets@mailworks.org2. The adesklets_submit script assits you in the construction of such an email using the user configuration file $HOME/.adesklets_submit and the command line switches. Here is an example of a valid $HOME/.adesklets_submit configuration:

# Simple demo configuration file for the submit.py script coming with adesklets.
# 
smtp_host = 'localhost'
smtp_port = 25
cc_to_self = True

info = { 'author_name'  : 'Belial Leviathan',
         'author_email' : 'leviathan@devil.net',
         'send_confirmation' : False
}

desklets = { 'beast' : { 'version' : '0.666.0', 
                         'thumbnail' : 'http://devil.net/beast_thumb.jpg',
                         'screenshot' : 'http://devil.net/beast_screen.jpg',
                         'download' : 'http://devil.net/malware/beast-0.666.0.tbz2',
                         'host_on_sourceforge': False,
                         'category': None,
                         'description' : 'Beware the power of this desklet!' 
             }
}
This is pretty self-explanatory, but here are a few less obvious points:

For example, Belial Leviathan would fisrt check his beast desklet's entry by doing something similar to:

     adesklets_submit beast

If everything goes fine, it will output the resulting submission email on stdout. From there, Belial can either:

     adesklets_submit --send beast

One last thing: you should try to avoid sending minor corrections multiple times, especially if you use local files. It both adds to the workload of the maintainer's email server and to the management work. Please try to create a valid entry then send it, not the other way around.

F.3.1 Further submission validation using adesklets_checkin

From adesklets 0.4.5, you now have access to the adesklets_checkin script as well. This is the Python script that the maintainer uses for checking in all submissions. Be aware that this script is only provided to desklet authors as a convenience, to lower their submission rejection count–developers are in no way forced to use it, and may even be unable to do so, since the script was not written with portability in mind as adesklets_submit was. Look at the script header for a complete list of requirements.

adesklets_checkin has two modes of operation: interactive and non-interactive. Only the non-interactive mode will interest desklet authors. In this mode, usage is fairly simple. Belial, for instance, would do:

     adesklets_submit beast | adesklets_checkin

If everything goes fine, an output similar to this will be produced:

     Validation started. Please wait.
     Everything seems fine, but keep in mind a few things cannot be
     verified without human intervention. See documentation for details.

If not, you will get an exception trace with some (hopefully) meaningful explanations.

F.3.2 Limitations of adesklets_checkin in non-interactive mode

Here are the remaining problems that adesklets_checkin cannot detect and thus must absolutely be solved manually (the maintainer would interactively catch most of them, and you would have to resubmit anyway):


Footnotes

[1] It is probably not a good idea to give away your private email adress here; for spam-related reasons, you should probably open an account on SourceForge , or at another similar place with a serious spam containment infrastructure.

[2] It is useless to send anything else to this address; all messages that cannot be parsed by the automatic reception script are just silently dropped. Write to syfou@users.sourceforge.net instead if you want to get in touch with the maintainer.