Changes between Version 7 and Version 8 of HackProcedures


Ignore:
Timestamp:
Mar 20, 2016, 11:34:52 AM (20 months ago)
Author:
figaro
Comment:

Added Trac hack tagging guidelines

Legend:

Unmodified
Added
Removed
Modified
  • HackProcedures

    v7 v8  
    1 [[PageOutline(2-5,Content)]]
     1[[PageOutline(2-5,Contents)]]
    22
    33= Hack Procedures
    44
    5 The TracHacks page contains more information, contact details, bug reports, enhancements, suggestions, etc.
     5This page lists some procedures around adding and maintaining Trac hacks. The TracHacks page contains more information, contact details, bug reports, enhancements, suggestions, etc.
    66
    7 == How to Contribute
     7== Contributing a hack
    88
    9 We have made things as simple as possible:
     9To contribute a hack, do the following:
    1010
    11  1. [/register Register] a user name then [/login login] (requires cookies).
     11 1. [/register Register] a user name and [/login login] with that name (requires cookies).
    1212 1. Fill out the NewHack form.
    13  1. Verify all the details for your new page are correct.
    14  1. Commit your code to the provided Subversion URL. Alternatively you can simply attach your hack to your Wiki page, but you can't delete or replace attachments.
     13 1. Verify that all the details for your new page are correct.
     14 1. Commit your code to the provided Subversion URL. Alternatively, you can attach your hack to your Wiki page, but you can't delete or replace attachments.
    1515 1. Consider subscribing to the [wiki:WikiStart#FeedbackandSuggestions trac-hacks mailing list].
    1616
    17 === List Your Own Hack Hosted Elsewhere
     17=== List your own hack hosted elsewhere
    1818
    19 Feel free to create a stub page here with a short description and links to your own hack. Please stick to the page naming convention, by appending the hack type, eg. '''Gantt Plugin'''. Therefore the !DoStuff macro should get a page named `DoStuffMacro`.
     19Feel free to create a stub page here with a short description and links to your own hack. Please adhere to the page naming convention by appending the hack type, so that a plugin that creates Gantt charts is called '''!GanttPlugin''' and a generic !DoStuff macro is named '''DoStuffMacro'''.
    2020
    21 Once you have created your page, tag it with the hack type and it will appear on the HackIndex. Tag it with your TracHacks [wiki:user] ID, if you want it to show up on your user page.
     21Once you have created your page, tag it with the hack 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.
    2222
    2323=== Adopt Unmaintained Hacks
     
    2525See AdoptingHacks.
    2626
    27 == How to Use Tags
     27== Trac hacks tag guidelines
    2828
    29 TracHacks uses TagsPlugin to add basic categorisation to its Trac content.
     29Tags are keywords that can be added to your hack and provide a broad categorisation to your hack to indicate its type and scope. Tags can be added to your hack through the keywords field, which is present at the bottom of the hack's wiki page. Tags are entered as free format text and therefore need to be maintained manually.
    3030
    31 === Meta-tags
     31=== Finding tags and plugins using tags
    3232
    33 Additionally, TracHacks uses a couple of [wiki:metatag metatags] when creating new hacks; [wiki:release release] and [wiki:type type].
     33 - The currently used tags can be found on the Trac hacks tag cloud: https://trac-hacks.org/tags
     34 - The hacks meeting a certain keyword, say `notification`, can be found as follows: https://trac-hacks.org/tags/notification?wiki=on
     35 - Hacks sharing the same tag can be found by adding the following macro to your wiki page: `[[ListTagged(notification)]]`
    3436
    35   '''''Please don't abuse this.'''''
     37=== Purpose
    3638
    37 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. That's quite a confusing sentence, so just take a look at [wiki:type type] for an example.
     39Tags make your hack accessible to a wider audience in the following ways:
     40 1. gives an indication of how well tested and maintained your hack is
     41 1. makes other hacks that offer similar functionality easier to find
     42 1. gives an indication of the functional scope of your hack
     43
     44=== Tag guidelines
     45
     46When authoring or maintaining hacks, always make sure the tags are up to date by providing at least these keywords:
     47 - Type: `plugin`, `script`, `macro`, `theme`, `patch`. See [wiki:type type].
     48 - Trac release number for which the plugin has been tested: `0.12`, `1.0` etc. See [wiki:release release].
     49 - License: a list of available licenses is at DevGuide#Licensing.
     50 - 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.
     51
     52Tag 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.
     53
     54== Meta-tags
     55
     56TracHacks uses the TagsPlugin to add basic categorisation to its Trac content.
     57
     58Additionally, TracHacks uses a couple of [wiki:metatag metatags] when creating new hacks: [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.
    3859
    3960== Site-specific TracLinks
     
    4869== Community and Site Evolution
    4970
    50 Following proposals hold more ideas on best-practice and may even yield procedures and guidelines in the future:
     71The following proposals hold more ideas on best practices and may even yield procedures and guidelines in the future:
    5172[[ListTagged(proposal)]]
    5273
    53 You're heartily invited to join in for discussion and even more suggestions.
     74You are heartily invited to join in for discussion and your own suggestions.
    5475
    5576----