English

Comment utiliser les outils du Lab ?

Dotclear fournit un ensemble d'outils pour le développement d'extensions pour Dotclear :

• un SVN
• un wiki
• un trac

Cette page est destinée à vous aider à vous familiariser avec ces outils et l'environnement du Lab.

Guide de démarrage rapide

Si vous connaissez déjà les commandes de SVN, l'adresse du dépôt est  https://svn.dotclear.net/lab/, vous pouvez récupérer toute l'arborescence du dépôt grâce à cette commande :

svn checkout https://svn.dotclear.net/lab/

Après avoir ajouté un plugin ou un thème, vous devez l'enregistrer sur le Trac et créer automatiquement sa page wiki grâce à ce formulaire (vous devrez être connecté) : http://lab.dotclear.org/register-extension

Présentation de SVN

SVN est la contraction de  Subversion. Subversion permet de conserver toutes les versions des sources d'un logiciel (ou pour ce qui nous concerne ici d'un thème ou d'un plugin).

Il vous faut tout d'abord installer un client subversion sur votre ordinateur :

• Pour Windows, ça peut être par exemple  TortoiseSVN ou  RapidSVN
• Pour Mac vous pouvez utiliser le Terminal et utiliser le subversion installé par défaut sur MacOSX en ligne de commande ou utiliser un client graphique comme  RapidSVN ou  ZigVersion
• Pour Linux, installez le package subversion puis utilisez les lignes de commande

Sur Windows, MacOs X and Linux, vous pouvez utiliser  RapidSVN, un client graphique pour SVN.

Les commandes SVN

Voici les principales commandes à connaître pour utiliser Subversion.

checkout

Permet de récupérer le « dépôt » (repository) et d'en faire une copie de travail (working copy)

# Pour récupérer tous les plugins
svn checkout https://svn.dotclear.net/lab/plugins

# Pour récupérer un plugin en particulier (ici acronyms)
svn checkout https://svn.dotclear.net/lab/plugins/acronyms 

update

Met à jour votre copie de travail avec la version la plus récente sur le dépôt. Le dépôt étant commun à tous il est important de mettre systématiquement à jour votre copie de travail avant d'y effectuer vos changements

# Mettre à jour votre copie de travail
svn update

commit

Permet d'envoyer sur le dépôt les modifications que vous avez apportées à votre copie de travail. Chaque envoie crée une nouvelle version du dépôt. Les autres utilisateurs récupéreront vos modifications lorsqu'ils mettront à jour leur propre copie.

# Envoyer tous ses changements au dépôt (pensez à mettre "un bref message" informant sur la nature de vos changements)
svn commit -m "message to annonce changes"

# Envoyer un changement sur un plugin ou un thème en particulier (pensez au "message")
svn commit -m "message to annonce changes" acronyms/

# Commit all changes made with your text editor 
svn commit

Vous pouvez utiliser la syntaxe wiki lors d'un commit.

diff

Cette commande affichera les différences entre votre copie de travail et la versio la plus récente du dépôt

# Exemple pour comparer le fichier _define.php du plugin acronyms
svn diff plugin/acronyms/_define.php 

revert

Permet de rétablir votre copie de travail en l'état de la dernière version du dépôt (utile si vous pensez avoir fait des bêtises chez vous).

# Exemple pour rétablir le fichier _public.php du thème Noviny de votre copie de travail tel que sur le dépôt
svn revert themes/Noviny/_public.php

# Exemple sur tous les fichiers d'un thème ou d'un plugin (ici moreTpl)
svn revert -R plugin/moreTpl

add

Ajoutera un dossier ou un fichier au dépôt (et les élements du dossier si vous ajoutez un dossier). Puis après cette opération vous pourrez faire le commit.

# Exemple pour ajouter le fichier user.png au thème Noviny
svn add themes/Noviny/images/user.png

# Exemple pour ajouter un répertoire images et tout son contenu au thème Noviny
svn add /themes/Noviny/images

mkdir

Créera et ajoutera un nouveau répertoire dans votre copie locale ou directement sur le dépôt SVN. La commande mkdir fera un commit automatique contrairement à la commande add

# Pour créer un nouveau répertoire de plugin 
svn mkdir plugins/myNewPlugin

move

Pour déplacer un fichier.

# Déplacer le fichier icon.png de acronyms vers myNewPlugin
svn move plugins/acronyms/icon.png plugin/myNewPlugin

copy

Pour copier le contenu d'un répertoire vers une autre destination.

# Exemple : copier le contenu du répertoire gallery/trunk vers gallery/tags/2.1
svn copy plugins/gallery/trunk plugin/gallery/tags/2.1

merge

Pour combiner/fusionner deux versions. Utile quand deux contributeurs bossent ensemble sur le même fichier

# To apply all changes made from $revision_number_start$ to $revision_number_start$ on plugin/gallery/branches to the destination plugin/gallery/trunk
svn merge -r $revision_number_start$:$revision_number_stop$ plugin/gallery/branches plugin/gallery/trunk

resolved

Résoudre les conflits éventuels générés par plusieurs commits concomittants sur le même fichier.

# Exemple pour le fichier _define.php d'acronym
svn resolved plugins/acronyms/_define.php

Note: si vous utilisez un client subversion graphique ces commandes se trouvent dans les menus de l'application ou par clic droit et menu contextuel subversion (selon le client que vous aurez choisi).

Exemples d'utilisation

Pour ces exemples, je prendrai comme référence un plugin et un thème fictifs appelés monPlugin et monTheme. Les chemins sur votre copie locale sont ainsi :

# For myPlugin
PLUGINPATH = /chemin/du/plugin/sur/la/copie/local/monPlugin
# For myTheme
THEMEPATH = /chemin/du/theme/sur/la/copie/local/monTheme

Ajouter un nouveau plugin / thème

Vous avez créé votre nouveau plugin / theme à l'emplacement PLUGINPATH et / ou THEMEPATH. Vous avez besoin en premier lieu de créer le répertoire sur le SVN qui va accueillir votre nouvelle création de la manière suivante :

# Pour monPlugin
svn mkdir https://svn.dotclear.net/lab/plugins/monPlugin
# Pour monTheme
svn mkdir https://svn.dotclear.net/lab/themes/monTheme

Le répertoire est maintenant créé sur le SVN. Faites alors un checkout pour instancier sur votre copie locale ce nouveau répertoire :

# Pour monPlugin
svn checkout https://svn.dotclear.net/lab/plugins/monPlugin PLUGINPATH
# Pour monTheme
svn checkout https://svn.dotclear.net/lab/themes/monTheme THEMEPATH

Maintenant, ajoutez au SVN les fichiers de votre plugin / thème:

# Pour monPlugin
svn add PLUGINPATH/*
# Pour monTheme
svn add THEMEPATH/*

Votre plugin / thème est maintenant correctement déposé sur le SVN

Note: Ne pas oublier de remplir le formulaire suivant : http://lab.dotclear.org/register-extension afin d'enregistrer votre plugin / thème sur le trac et de créer automatiquement sa page wiki

Mettre à jour votre copie locale

si des changements ont été apporté à votre plugin / thème sur le SVN, il est nécessaire de faire une mise à jour de votre copie locale par le biais de cette commande :

# Pour monPlugin
svn update PLUGINPATH
# Pour monTheme
svn update THEMEPATH/*

"Commiter" vos changements sur le SVN

Vous avez fait des modifications sur votre copie locale et vous voulez les "commiter" sur le SVN :

# Pour monPlugin
svn commit PLUGINPATH
# Pour monTheme
svn commit THEMEPATH

Ajouter des fichiers sur le SVN

Parfois, vous avez besoin d'ajouter des fichiers au SVN :

# Pour monPlugin
svn add PLUGINPATH/filesto.add
# Pour monTheme
svn add THEMEPATH /filesto.add

Il vous suffira ensuite de "commiter" les changements pour qu'ils apparaissent sur le SVN.

Le développement de Dotclear se fait avec Mercurial, pourquoi Dotclear Lab utilise SVN ?

La gestion centralisée mise en place par SVN est plus efficace si le dépôt contient de nombreux projets (les plugins et les thèmes). Si Dotclear Lab utilisait une gestion décentralisée comme Mercurial, chaque développeur devrait télécharger tous les plugins et tous les thèmes, même pour modifier un seul module.

Wiki

Le Wiki est un outil qui permet aux visiteurs identifiés de créer et de modifier des pages. Il propose un éditeur et une syntaxe simplifiée de mise en forme. La syntaxe est détaillée sur cette page en anglais : WikiFormatting.

Créer des pages

Éditer les pages

Si vous avez les droits suffisants, un bouton "Edit page" est alors présent en bas de page. Cliquer sur ce bouton vous permettra de modifier son contenu puis de l'enregistrer en cliquant sur le bouton "Submit changes". Il est conseillé de vérifier vos modifications à l'aide du bouton "Preview Page".

Vous pouvez, si vous le désirez, préciser la nature des modifications apportées en complétant le champ intitulé "Change information" situé juste au dessus des boutons de commande.

Déposer vos fichiers

Vous pouvez attacher des pièces jointes (images, .zip de vos créations, fichiers README, etc.) aux pages du Wiki. Pour cela, cliquez sur Attach file en bas de la page où vous voulez déposer un fichier.

Tous les utilisateurs peuvent envoyer des nouveaux fichiers ou mettre à jour un fichier existant de même nom en cochant Replace existing attachment of the same name lors de l'envoi du fichier, mais seuls les administrateurs peuvent les effacer (n'hésitez pas à les contacter pour supprimer un fichier). Ainsi, pour éviter d'avoir autant de fichiers attachés que de versions de votre thème ou plugin, vous pouvez supprimer le numéro de version du nom du fichier et l'indiquer dans la description du fichier. Par exemple :

Plugin version 1.0.42

À la prochaine mise à jour, renvoyez un fichier avec le même nom en cochant Replace existing attachment of the same name pour remplacer l'ancienne version du fichier.

Vous pouvez aussi entrer un lien direct vers le fichier dans la description du fichier, il sera directement utilisable pour installer un module depuis son URL :

http://lab.dotclear.org/raw-attachment/wiki/[plugin ou theme]/[nom de la page wiki]/[nom du fichier]

Trac

License

Seul le code publié sous une  licence libre est autorisé sur Dotclear Lab. Les licences autorisées sont GPL v2 et v3, BSD, LGPL, MPL, etc.

La licence Creative Commons peut être utilisée pour les thèmes, mais pas pour les plugins (voir la  FAQ CC).