Contributing Code

You can contribute code to TiddlyWiki by submitting changes to the main core code, or by submitting your own plugins.

General Guidelines for Submitting Code

In general, Subversion works best if you do a separate commits for each change; don't bundle up several modifications into one commital. Above all else, make sure that you include a commit message that contains enough information to make sense when read in the context of Trac's 'Timeline' view. This is really important - a blank commit message forces other developers to check through your changes in detail to figure out what has changed.

Guidelines for Core Code Contributors

Code submissions for the TiddlyWiki core code are welcomed from anybody with any improvements to contribute. Like many open source projects, at any given time checkin rights are restricted to a small number of trusted developers. For everyone else, the best way to submit code is via email or a posting in the  discussion group.

Regardless of how your code is submitted, it's much more likely be accepted if you follow these guidelines:

• Nearly universally useful (if it's very specialised, it probably belongs in a plugin)
• Impractical to offer as a plugin
• Use the same CodingConventions as the existing core code. Even if your preferred conventions are better...
• Test the change on all major browsers

Guidelines for Plugin Contributors

If you're an approved committer for the project, you will have a personal directory under the contributors directory in the SourceTree. Your plugins should be placed in a subdirectory called plugins. For example,

/Trunk/contributors/EricShulman/plugins.

Plugins are specially treated by the Cook process enabling them to be stored in human readable form (as opposed to ordinary tiddlers which are somewhat obfuscated by the \n escaping and so on). A plugin called MyPlugin is formed out of up to three separate files:

• MyPlugin.js is the text of the plugin
• MyPlugin.deps references any dependent tiddlers or plugins that should be automatically cooked along with this plugin (it uses the same syntax as RecipeFiles?)
• MyPlugin.js.meta is a text file containing the metadata about the plugin (see below)

The metadata file looks like this:

title: MyPlugin
modifier: EricShulman
tags: systemConfig

Each metadata item corresponds to one of the attributes of the plugin tiddler. Other attributes that can be set are "modified" (for the last modified date of the plugin, and "created" for the creation date of the plugin).

Guidelines for Plugin Documentation

A plugin should normally contain three items of documentation:

1. A header table containing the plugin essentials: its title, author etc
2. A summary describing what the plugin does
3. A usage section, describing how to use the plugin

The header table should normally contain at least the following:

Name:	The name of the plugin
Description:	A one line description of the plugin
Author:	The name of the author of the plugin
Source:	where a user can obtain the plugin, eg:  http://www.MyWebSite.com/#ExamplePlugin
CodeRepository:	the code repository of where the plugin is stored, if any
Version:	The version number of the plugin, useful for when users report bugs
Status:	The plugin's status, eg released, beta etc
Date:	The date when the plugin was written
Comments:	A place where the user can make comments about the plugin, eg at  http://groups.google.co.uk/group/TiddlyWiki
License:	The license for the plugin, essential if you want to allow others to use your plugin
~CoreVersion:	The version of TiddlyWiki required to run the plugin (eg 2.3)

The summary should be a short paragraph describing what the plugin does.

The usage section should describe how to use the plugin, its parameters (if any) and any other things the user might need to know to use the plugin.

If the documenation for a plugin is very large you may wish to put it in a separate tiddler (for example, MyPluginDoc?) and link to it from the plugin. This means that users of your plugin can delete the documenation from their TiddlyWiki once then no longer require it.

There is an example plugin at:

 http://svn.tiddlywiki.org/Trunk/contributors/MartinBudden/plugins/ExamplePlugin.js

that you can use for reference, or as a template for your plugins.