[[PageOutline(2-5,Contents)]]

= Plugin Procedures

This page lists some procedures around adding and maintaining Trac plugins. The TracHacks page contains more information, contact details, bug reports, enhancements and suggestions.

== Contributing a plugin

To contribute a plugin, do the following:

 1. [/register Register] a user name and [/login login] with that name (requires cookies).
 1. Fill out the NewHack form.
 1. Verify that all the details for your new page are correct.
 1. Commit your code to the provided Subversion URL. Alternatively, you can attach your plugin to your Wiki page, but you can't delete or replace attachments.
 1. Consider subscribing to the [wiki:WikiStart#FeedbackandSuggestions trac-hacks mailing list].

=== List your own plugin hosted elsewhere

Feel free to create a stub page here with a short description and links to your own plugin. Please adhere to the page naming convention by appending the plugin type, so that a plugin that creates Gantt charts is called '''!GanttPlugin''' and a generic !DoStuff macro is named '''DoStuffMacro'''.

Once you have created your page, tag it with the plugin type and it will appear on the HackIndex. Tag it with your [wiki:user TracHacks user ID], if you want it to show up on your user page.

=== Adopt Unmaintained Plugins

See AdoptingHacks.

== Trac plugins tag guidelines

Tags are keywords that can be added to your plugin and provide a broad categorisation to your plugin to indicate its type and scope. Tags can be added to your plugin through the keywords field, which is present at the bottom of the plugin's wiki page. Tags are entered as free format text and therefore need to be maintained manually.

=== Finding tags and plugins using tags

 - The currently used tags can be found on the tag cloud: https://trac-hacks.org/tags
 - The plugins meeting a certain keyword, say `notification`, can be found as follows: https://trac-hacks.org/tags/notification?wiki=on
 - Plugins sharing the same tag can be found by adding the following macro to your wiki page: `[[ListTagged(notification)]]`
 - When referring to plugins with similar functionality on your wiki page, use `[[ListTagged(realm:wiki notification)]]`

=== Purpose

Tags make your plugin accessible to a wider audience in the following ways:
 1. gives an indication of how well tested and maintained your plugin is
 1. makes other plugins that offer similar functionality easier to find
 1. gives an indication of the functional scope of your plugin

=== Tag guidelines

When authoring or maintaining plugins, always make sure the tags are up to date by providing at least these keywords:
 - Type: `plugin`, `script`, `macro`, `theme`, `patch`. See [wiki:type type].
 - Trac release number for which the plugin has been tested: `0.12`, `1.0` etc. See [wiki:release release].
 - License: a list of available licenses is at DevGuide#Licensing.
 - Functional attributes: some keywords that would broadly categorise the scope and functionality of your plugin, see the tag-cloud for helpful options to choose from.

Tag keywords can be either plural or singular. It is recommended to use the keyword that is already being used, whether that is singular or plural. Having both plural and singular would otherwise obscure the meaning behind them.

== Meta-tags

TracHacks uses the TagsPlugin to add basic categorisation to its Trac content. 

Additionally, TracHacks uses a couple of [wiki:metatag metatags] when creating new plugins: [wiki:release release] and [wiki:type type]. '''Please don't abuse this.''' If a tag page (eg [wiki:macro macro]) is itself tagged with one of the meta-tags, it will be included as an option in NewHack. To understand what this means, just take a look at page [wiki:type type] as an example.

== Site-specific TracLinks

We have defined some InterTrac and InterWiki links for commonly used realms, such as `google:search` and `trac:wikipage`. See InterTrac#ListofActiveInterTracPrefixes and InterMapTxt for a complete list.

Examples:
 * [wiki:user Registered users] of TracHacks
 * Plugins for Trac [wiki:0.12], [wiki:1.0] and [wiki:1.2]

== Community and Site Evolution

The following proposals hold more ideas on best practices and may even yield procedures and guidelines in the future:
[[ListTagged(proposal)]]

You are heartily invited to join in for discussion and your own suggestions.

----
See also: TracHacks, TracHacks/SiteMaintenance, AdoptingHacks