Changes between Version 8 and Version 9 of DevGuide

Timestamp:

Jun 18, 2014, 2:24:08 AM (10 years ago)

Author:

Ryan J Ollos

Comment:

Recommendations for adding metadata to a single file plugin.

DevGuide

@@ -38 +38 @@
 Currently 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).
 
+== Metadata for Single-File Plugins
+
+Plugins 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`).
+
+{{{#!python
+revision = "$Rev$"
+homepage = "http://trac-hacks.org/wiki/MyAmazingMacro"
+license = "3-Clause BSD"
+author = "Guido van Rossum"
+author_email = "trac@python.org"
+}}}
+
+The 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.
+
+For 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.
+
+{{{#!python
+homepage = '$URL$'
+version = '$Rev$'
+}}}
+
+{{{#!python
+url = '$URL$'
+revision = '$Rev$'
+}}}
+
+The 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.
+{{{#!sh
+svn propedit svn:keywords MyAmazingMacro.py
+}}}
+
+Keep 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.
+
 == Coding Style