Submitting a desklet - adesklets 0.6.1
Description: adesklets 0.6.1

Next: Copying This Manual, 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:

- Submit a new or updated desklet description for inclusion on the adesklets web site ;
- Submit a bzip'ed desklet archive for inclusion in SourceForge's desklets package (this is optional–you may choose to host it yourself).

### 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:

- Try to avoid using pseudonyms and nicknames for the `author_name` as much as possible, unless, of course, you already have a pretty well-established online identity under this name.
- `send_confirmation` specifies if an email should be sent back to your `author_email` address whenever your desklet is succesfully published. If the submitted entry is rejected, you will always be written back anyway with an explanation. Usually, the maintainer will not try to make changes to problematic entries; it will only summarize back to the author what was not OK.
- Double check your `author_email` address, since this is the only one the maintainer will try to use when contacting you, regardless of what the headers say. Failing to supply a valid address will cause all messages to fail to be sent to you, and all new desklet entries will be rejected.
- You can very well use adesklets_submit without any prior contact with the adesklets maintainer (either via email, within the forum using this adress for registration, or through the mailing list), but some back and forth will be needed before publication just to assert your identity and its effective relation to the provided email address.
- `desklets` is a dictionary of dictionaries (one dictionary per desklet, desklets' names being the keys); all the items referring to files (thumbnail, screenshot and download) could either be publicly accessible URI's (this is the preferred method), or local files, either absolute or relative to your $HOME directory. In that case, needed files will be attached to the generated multipart email.
- All images will always be fetched and integrated on the adesklets.sf.net web site; you can safely remove them from your online location afterwards if you provided live URI's.
- When updating already included desklets, there is no need to submit back the `thumbnail` or `screenshot` images if they did not change; you can just as easily reference the already installed images on SourceForge:
  - The `thumbnail` is always stored under `http://adesklets.sf.net/images/NAME_thumb.[jpg|png]`
  - The `screenshot` is always stored under `http://adesklets.sf.net/images/NAME_screen.[jpg|png]` where `NAME` is the name of the desklet.
- Using the `host_on_sourceforge` value, you can choose to have your desklet package either hosted on SourceForge or just referenced on your site if you provided a URI. Of course, choosing this last alternative also means you will need to keep it in place.
- The `thumbnail` image should be a JPG (preferably) or PNG (if you really need higher resolutions) of dimensions lying between 190x35 and 230x110 pixels.
- The `screenshot` image should be a 640x480 JPG (preferably) or PNG. It should put your desklet in evidence, and thus contain no other ones.
- You can choose not to submit thumbnails and/or screenshots. In that case, default, generic images will be used instead.
- `Category` is unused for now, and just ignored.
- All emails weighing more than 300 KB will be rejected by the maintainer's email server; thus, adesklets_submit will refuse to generate them. Instead of submitting such big entries, use the URI facility described above to trim them down.
- `adesklets_submit` does not enforce the requirements above; it only checks what is strictly required to build a compliant submission email: the existence of dictionary entries, availability of files, the validity of file types if they are local... It is your duty to make sure the entries meet the other requirements if you want to avoid rejection.

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:

- Pipe it to his favorite MTA (mail transfert agent) to send it to adesklets@mailworks.org.
- Make `adesklets_submit` send it itself by SMTP, using the `smtp_host` and `smtp_port` parameters in its `$HOME/.adesklets_submit`. For this, Belial would use:

         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):

- Incomplete README file in base directory (Does it contain all the details enumerated above?).
- Out-of-date README file (Does its content reflect the current state of the desklet?).
- Desklet fails to run out-of-the-box (i.e. with or without minimal configuration) when requirements in the README file are met and special instructions are followed.

#### 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.