Soumettre un desklet - adesklets 0.6.1
Description: adesklets 0.6.1

Next: Copier ce Manuel, Previous: GNU Makefile pour empaqueter les desklets, Up: Top

## Appendix F Soumettre un desklet

### F.1 Minima requis dans un paquetage de desklet

Les règles sur le contenu du paquetage d'un desklet sont maigres; les auteurs sont libres de faire ce qu'ils veulent. Ils ne doivent absolument respecter que deux choses:

1. Le répertoire de base de l'archive du desklet doit contenir un fichier `README` très clair1 et tenu à jour. Il doit au moins contenir:
   - le nom et l'adresse email de l'auteur2
   - Une courte description du desklet
   - Ses dépendances
   - Comment s'en servir
2. Le paquetage doit être une archive tar bzippée ne contenant qu'un seul répertoire source du type `NOM-MAJEURE.MINEURE.REVISION`, où `NAME` est le nom de base du desklet, et `MAJOR.MINOR.REVISION` sa version. Veillez noter qu'un makefile (See GNU Makefile pour empaqueter les desklets.) est aussi fourni pour automatiser la création de ce genre d'archive sur les systèmes GNU.

### F.2 Le script `adesklets_submit`

Depuis `adesklets` 0.4.4, les auteurs de desklets disposent d'un script Pyhton automatisant la soumission de leurs desklets: `utils/adesklets_submit` dans le paquetage des sources. Utilisez l'option de configuration `--with-python-install-submission-scripts` pour le placer dans votre répertoire `bindir` lors de l'installation.

`adesklets_submit` peut être utilisé pour:

- Soumettre une nouvelle description, ou une mise à jour, à inclure dans le site Internet d'adesklets ;
- Soumettre une archive bzippée du desklet pour l'ajouter aux paquetages de desklets de SourceForge (c'est optionel–vous pouvez choisir de l'héberger vous-même).

### F.3 Invoquer `adesklets_submit`

La soumission du desklet commence par l'envoi d'un email formaté spécifiquement à adesklets@mailworks.org3. Le script `adesklets_submit` vous assiste dans la construction de cet email en utilisant le fichier de configuration `$HOME/.adesklets_submit` et des options de ligne de commande. Voici un exemple de configuration valide du fichier `$HOME/.adesklets_submit`:

    # 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!'
                 }
    }

Il s'explique assez bien de lui-même, mais voici quelques points moins clairs:

- Essayez autant que possible d'éviter les pseudonymes et les surnoms pour `author_name`, sauf si, évidemment, vous avez déjà une indentité virtuelle bien établie sous ce nom.
- `send_confirmation` précise si un email doit être envoyé en retour à l'adresse `author_email` dès que votre desklet est publié correctement. De toute façon si'l est rejeté vous serez toujours averti par email, avec quelques explications. Géneralement, le gérant n'essaiera pas de changer les données problématiques, il va seulement expliquer à l'auteur ce qui n'était pas bon.
- Verifiez deux fois l'adresse `author_email`, puisque c'est la seule que le webmestre essaiera d'utiliser pour vous contacter, ce que les en-têtes disent sera ignoré. Si vous ne fournissez pas une adresse valide tous les messages ne pourront vous être envoyés, et toutes les nouvelles entrées du desklet seront rejetées.
- Vous pouvez sans problème utiliser adesklets_submit sans aucun contact préalable avec le webmestre d'adesklets (que ce soit par email, dans le forum avec l'adresse donnée pour l'enregistrement, ou via la mailing-list), mais un minimum de communication sera nécessaire avant la publication simplement pour vérifier votre identité et sa relation effective avec l'adresse email fournie.
- `desklets` est un dictionnaire de dictionnaires (un dictionnaire par desklet, le nom des desklets étant les clefs); toutes les données se réferant à des fichiers (miniatures, captures d'écran ou fichiers à télecharger) peuvent être soit une adresse sur un site accessible publiquement (de préference), soit un chemin absolu ou relatif à votre répertoire $HOME vers des fichiers locaux. Dans ce cas, les fichiers requis seront attachés en pièce jointe à l'email géneré.
- Toutes les images seront rapatriées puis intégrées au site Internet adesklets.sf.net, vous pourrez ensuite sans problème les retirer de votre emplacement en ligne si vous avez fourni des URL.
- Si vous mettez à jour un desklet déjà en ligne, il n'y a pas besoin de soumettre les images `thumbnail` ou `screenshot` si elles n'ont pas changé; vous pouvez aussi facilement faire réference aux images déjà installées sur SourceForge:
  - `thumbnail` est toujours stockée sous `http://adesklets.sf.net/images/NAME_thumb.[jpg|png]`
  - `screenshot` est toujours stockée sous `http://adesklets.sf.net/images/NAME_screen.[jpg|png]` où `NAME` est le nom de votre desklet.
- En utilisant la valeur `host_on_sourceforge`, vous pouvez choisir si le paquetage de votre desklet sera hébergé sur SourceForge ou sur votre propre site si vous avez fourni une URL. Bien sur dans ce dernier cas vous devrez le maintenir à l'emplacement donné.
- L'image `thumbnail` doit être au format JPG (de préference) ou PNG (si vous avez vraiment besoin de définitions plus élevées) et d'une dimension comprise entre 190x35 pixels et 230x110 pixels.
- L'image `screenshot` doit être un JPG (de préference) ou un PNG de 640x480 pixels. Elle doit mettre votre desklet en évidence, et donc ne pas en contenir d'autres.
- Vous pouvez choisir de ne pas fournir de miniature ni/ou de capture d'écran. Dans ce cas, par défaut, des images géneriques seront utilisées à la place.
- `Category` est actuellement inutilisée, et sera juste ignorée.
- Tous les emails pesant plus de 300KB seront rejetés par le serveur email du webmestre, adesklets_submit refusera donc d'en génerer. Au lieu de soumettre d'aussi grosses entrées, utilisez la possibilité de donner des URLs comme décrit ci-dessus pour alléger l'email.
- `adeskets_submit` ne vérifie pas que vous respectez toutes ces règles; il ne vérifie que ce qui est strictement nécessaire pour construire un email de soumission adapté: l'existence des entrées de dictionnaire, la disponibilité des fichiers, la validité des types de fichiers locaux... Il est de votre devoir de s'assurer que les données sont correctes si vous voulez éviter le rejet.

Par exemple, Belial Leviathan devrait d'abord vérifier les données de son desklet `beast` en faisant quelquechose comme:

         adesklet_submit beast

Si tout fonctionne bien, l'email de soumission résultant sera affiché sur `stdout`. A partir de là, Belial peut:

- Le passer par un tuyau (pipe) à son MTA (agent de transfet d'email) favori pour l'envoyer à adesklets@mailworks.org.
- Demander à `adesklets_submit` de l'envoyer lui-même par SMTP, en utilisant les paramètres `smtp_host` et `smtp_port` dans son `$HOME/.adesklets_submit`. Pour cela, Belial devrait utiliser:

         adesklets_submit --send beast

Une dernière chose: essayez d'éviter d'envoyer des corrections mineures à plusieurs reprises, en particulier si vous utilisez des fichiers locaux. Cela va charger à la fois le server email du webmestre et son travail de gestion. Veillez essayer de créer une entrée valide puis de l'envoyer, au lieu de patauger autrement.

#### F.3.1 Validation approfondie d'une entrée avec `adesklets_checkin`

Depuis `adesklets` 0.4.5, vous avez aussi à votre disposition le script `adesklets_checkin`. C'est le script Python que le webmestre utilise pour vérifier toutes les soumissions. N'oubliez pas que ce script n'est fournit aux auteurs de desklets que par confort, pour minimiser le nombre de rejets de soumissions–les développeurs ne sont en aucun cas forcés de l'utiliser, et peuvent même être incapables de le faire, puisque ce script n'a pas été écrit avec le souci de la portabilité, contrairement à adesklets_submit. Lisez l'en-tête du script pour une liste complète des pré-requis à son exécution.

`adesklets_checkin` a deux modes de fonctionnement: interactif et non-interactif. Seul le mode non-interactif interessera les auteurs de desklets. Dans ce mode, l'utilisation est franchement simple. Belial, par exemple, ferait:

         adesklets_submit beast | adesklets_checkin

Si tout fonctionne bien, le résultat serait similaire à:

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

Sinon, vous aurez la trace de l'exception avec quelques explications assez claires (espèrons-le).

#### F.3.2 Limitations d'`adesklets_checkin` en mode non-interactif

Voici quelques problèmes restants qu'`adesklets_checkin` ne peut pas détecter et qui doivent donc être absolument résolus manuellement (le webmestre en détectera la plupart, et vous aurez à renvoyer l'email de toute façon):

- Un fichier README incomplet dans le répertoire de base (Est-ce qu'il contient tous les détails énumerés ci-dessus?).
- Le fichier README n'est plus à jour (Est-ce que son contenu reflète l'état actuel du desklet?).
- Le desklet ne peut pas fonctionner à la sortie de la boite (c'est-à-dire sans ou avec un minimum de configuration) alors que les pré-requis du fichier README et les instructions particulières sont respectés.

#### Footnotes

[1] NdT: et en anglais, pour plus de 'portabilité'.

[2] Ce serait surement une mauvaise idée que de publier votre adresse email privée ici; pour éviter le spam, vous devriez plutôt ouvrir un compte sur SourceForge , ou un autre fournisseur similaire disposant d'un bon système anti-spam.

[3] Il est inutile d'envoyer autre chose à cette adresse; tous les messages qui ne peuvent être interprétés par le script de réception automatique seront simplement supprimés. Ecrivez plutôt à syfou@users.sourceforge.net si vous désirez contacter le créateur du projet (qui parle très bien français, NdT).