Changes between Version 8 and Version 9 of DevGuide


Ignore:
Timestamp:
Jun 18, 2014, 4:24:08 AM (5 months ago)
Author:
rjollos
Comment:

Recommendations for adding metadata to a single file plugin.

Legend:

Unmodified
Added
Removed
Modified
  • DevGuide

    v8 v9  
    3838Currently it is not recommended to add license text to static resources (i.e. file in `htdocs`), since doing so will increase the size of the content that is sent to the client. This issue will be addressed in the Trac core when support is added for minimization (trac:#10672).
    3939
     40== Metadata for Single-File Plugins
     41
     42Plugins are typically packaged using setuptools egg format, but Trac also supports single-file plugins.  A single-file plugins is a single `.py` file that is placed in the project or shared `plugins` directory.  While the metadata for a packaged plugin is stored in it's `setup.py` file, the metadata for a single-file plugin can added using file-scope attributes.  The supported attributes and their aliases are: `author`, `author_email`, `home_page` (`url`), `license`, `trac` and `version` (`revision`).
     43
     44{{{#!python
     45revision = "$Rev$"
     46homepage = "http://trac-hacks.org/wiki/MyAmazingMacro"
     47license = "3-Clause BSD"
     48author = "Guido van Rossum"
     49author_email = "trac@python.org"
     50}}}
     51
     52The attributes should be self-explanatory with the possible exception of the `trac` attribute. The `trac` attribute is used to direct bug reports to an issue tracker that differs from `homepage`. If the plugin is hosted on trac-hacks.org and the `homepage` attribute is set to point to the project wiki page, the `trac` attribute will not need to be set.
     53
     54For files stored in Subversion, [http://svnbook.red-bean.com/en/1.4/svn.advanced.props.special.keywords.html Keyword Substitution] is supported for the `homepage` (`url`) and `version` (`revision`) attributes.
     55
     56{{{#!python
     57homepage = '$URL$'
     58version = '$Rev$'
     59}}}
     60
     61{{{#!python
     62url = '$URL$'
     63revision = '$Rev$'
     64}}}
     65
     66The file's `svn:keywords` property must be edited to append `Rev` and/or `URL`.  Note that the aliases `Revision`, `LastChangedRevision` and `HeadURL` are not supported.
     67{{{#!sh
     68svn propedit svn:keywords MyAmazingMacro.py
     69}}}
     70
     71Keep in mind that keywords are only expanded when the files are checked-out of version control. If the files are downloaded directly from a Trac repository or the repository is cloned using Git-SVN, then the keywords will not be expanded in the source.
     72
    4073== Coding Style
    4174