Français

How to use lab tools ?

Dotclear lab provides you with a set of tools for development of Dotclear extensions. It is composed of:

• SVN
• Wiki
• Trac groupware

This page helps you to familiarize with this new environment and how to use these tools.

Quick Start Guide

If you are familiar with SVN, the repository's addess is  https://svn.dotclear.net/lab/, you can grab all the repository tree with this command :

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

Once your plugin or theme has been comitted to the repository, you will have to register it on this Trac. That procedure will create its wiki page and can be found at : http://lab.dotclear.org/register-extension (you have to be logged in to do so.)

SVN

SVN is a contraction of  SubVersioN. You can get all lab source codes with this software. First of all, you need to install a SVN client on your computer:

• For Windows, use  tortoiseSVN
• For MacOs X, use the default SVN client (already installed) using command line
• For Linux / Unix, use the normal SVN client by installing package subversion

On Windows, MacOs X and Linux, you can use  RapidSVN, a visual client for SVN.

SVN commands

When this step is done, you can now retrieve all you want in Lab. For a normal utilisation, you have to know just several SVN commands:

checkout

Will retrieve and create a local copy of the repository. You need to use this command only the first time.

# To retrieve all plugins
svn checkout https://svn.dotclear.net/lab/plugins

# To retrieve a specific plugin like acronyms
svn checkout https://svn.dotclear.net/lab/plugins/acronyms

update

Will update your local copy to the most recent revision. You are not alone to make changes, for this reason you need to have a local copy up to date before making any change.

# Update your local copy
svn update

commit

Will commit to the reposity all changes you made on your local copy. After that, a new revision is released to others. They can get it by an update.

# Commit all changes made
svn commit -m "message to announce changes"

# Commit all changes made in acronyms plugin (if you are in /plugins directory)
svn commit -m "message to announce changes to acronyms/

# Commit all changes made with your text editor
svn commit

You can use the wiki syntax in your commits.

diff

Will show you all differences beetween your local copy and the latest revision

# To display changes beetween you local copy and the last revision of
_define.php in acronyms plugin
svn diff plugin/acronyms/_define.php

revert

Will remove all changes you made in your local copy.

# To remove all changes made on _public.php in Noviny theme
svn revert themes/Noviny/_public.php

# To remove all changes made on moreTpl plugin. That includes
subdirectories and files. Don't forget -R option for recursivity
svn revert -R plugin/moreTpl

add

Will add to the repository new $file$ or new $directory$ (including files inside). To release and validate this addition, you have to make a commit afterwards.

# To add user.png on Noviny theme
svn add themes/Noviny/images/user.png

# To add images directory on Noviny theme
svn add /themes/Noviny/images

mkdir

Will create a new directory and add it automaticaly. As add, you have to make a commit afterwards.

# To create a new plugin
svn mkdir plugins/myNewPlugin

move

Will move files to other destination.

# To move icon.png from acronyms to myNewPlugin
svn move plugins/acronyms/icon.png plugin/myNewPlugin

copy

Will copy all files to other destination

# To copy trunk to a stable tag
svn copy plugins/gallery/trunk plugin/gallery/tags/2.1

merge

Will merge changes of two different revisions. That's usefull when two contributors commit theirs versions at the same time

# 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

Will resolve conflicts that can happen during an update like two or more commits at the same time on the same file

# To resolve conflicts during an update on _define.php
svn resolved plugins/acronyms/_define.php

Note: For those who use tortoiseSVN on a windows computer, all commands described below are passed through a graphical interface (right click on finder).

Examples

For those examples, i will take a fictive new plugin and theme called myPlugin and myTheme. Paths on your local copy for them are:

# For myPlugin
PLUGINPATH = /path/on/plugin/directory/in/your/local/copy/myPlugin
# For myTheme
THEMEPATH = /path/on/theme/directory/in/your/local/copy/myTheme

Add a new plugin / theme

You have created your new plugin / theme located on PLUGINPATH and THEMEPATH. First, you need to create directory on the SVN following this step:

# For myPlugin
svn mkdir https://svn.dotclear.net/lab/plugins/myPlugin
# For myTheme
svn mkdir https://svn.dotclear.net/lab/themes/myTheme

Directory is now created. Let's do a chekout to get this new directory:

# For myPlugin
svn checkout https://svn.dotclear.net/lab/plugins/myPlugin PLUGINPATH
# For myTheme
svn mkdir https://svn.dotclear.net/lab/themes/myTheme THEMEPATH

Now, add files on SVN:

# For myPlugin
svn add PLUGINPATH/*
# For myTheme
svn add THEMEPATH/*

Your plugin / theme is now updated on SVN.

Note: Don't forget to add component and wiki page by filling the form on this address: http://lab.dotclear.org/register-extension

Update your local copy

Changes are made on myPlugin / myTheme. Your need to update your local copy following this step:

# For myPlugin
svn update PLUGINPATH
# For myTheme
svn update THEMEPATH/*

Commit your changes on SVN

You made changes on your local copy and you want to commit them on SVN. Follow this step:

# For myPlugin
svn commit PLUGINPATH
# For myTheme
svn commit THEMEPATH

Add files on SVN

Sometimes, you need to add files in myPlugin / myTheme. To commit changes, follow this step:

# For myPlugin
svn add PLUGINPATH/filesto.add
# For myTheme
svn add THEMEPATH /filesto.add

Afterwards, just commit your changes.

Mercurial is used for Dotclear Development, why Dotclear Lab use SVN?

A centralised version management (like SVN) is more efficient with multiple projects (plugins and themes). If Dotclear Lab used Mercurial, each developer would have to download all the plugins, even to update only one plugin.

Wiki

Wiki is a tool to create pages with many contributors. It provides a simplified syntax to edit them. You can check this syntax on the page WikiFormatting

Create pages

First, go to the URL you want to create. The trac wiki supports "sub-categories" so choose very carefully your URL so as to make sense. When you arrive, it's a blank page. If you have sufficient rights, you shoudl have a button "Create this page".

Just click on it and describe your page.

Edit pages

If you have sufficient rights, on each wiki page you should find a button named "Edit page". You can click on it to modify something inside.

For both these actions, before submitting changes, verify them by previewing your job and describe what you did in field "change information". It will show on timeline after.

Add your files

You may attach files (images, zip archives , README files, etc.) to wiki pages. For that, click on the Attach files button at the bottom of the page in which you want to add a file.

All users may send new files or update existing files by checking Replace existing attachment of the same name when sending files, but only administrators can delete them (feel free to contact them to delete a file). Therefore, to avoid having as many files as versions of your theme or plugin, you may delete the file's version number and mention it in file description. For example:

Plugin version 1.0.42

When you next update, send a file with the same name and check "Replace existing attachment of the same name to replace the old version of the file.

You may also provide a direct link to the file in its description, it will be directly available to install a module from its URL:

http://lab.dotclear.org/raw-attachment/wiki/[plugin or theme]/[wikipage name]/[file name]

Trac groupware

License

Only code under  free software license ("free" as in "free speech," not as in "free beer") is authorized on Dotclear Lab. The authorized licenses are GPL v2 and v3, BSD, LGPL, MPL, etc.

The Creative Commons license can be used for themes, but not for plugins (see  CC FAQ).