How to use lab tools ?
Dotclear lab provides you with a set of tools for development of Dotclear extensions. It is composed of:
- 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 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.
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:
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
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
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.
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
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
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
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
Will move files to other destination.
# To move icon.png from acronyms to myNewPlugin svn move plugins/acronyms/icon.png plugin/myNewPlugin
Will copy all files to other destination
# To copy trunk to a stable tag svn copy plugins/gallery/trunk plugin/gallery/tags/2.1
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
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).
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 and the themes, even to update only one of them.
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
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.
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]
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).