Changes between Version 16 and Version 17 of DevGuide


Ignore:
Timestamp:
May 2, 2015, 11:48:13 AM (9 years ago)
Author:
figaro
Comment:

Cosmetic changes

Legend:

Unmodified
Added
Removed
Modified

  • DevGuide

    v16 v17  
    11[[PageOutline(2-5,Contents,pullout)]]
     2
    23= Plugin Development Guide
    34
    45This document captures some best practices and guidelines for plugin development. It is a community driven document, and everyone is encouraged to contribute to it. If you have questions or comments, please raise them on the [trac:MailingList Trac-dev MailingList].
    56
    6 == License
     7== Licensing
    78
    89Plugin authors are encouraged to clearly indicate how the contribution is licensed. This is important for both users and future developers of your plugin. Having a clearly defined license allows someone else to adopt and carry on development of the plugin if you choose to no longer support it. It is also important for users and administrators who need to understand the terms and conditions under which they can use or modify the code.
    910
    10 Trac-Hacks is an open source community driven by voluntary contributions and made successful by collaboration. Therefore we encourage the use of licenses that foster collaboration and minimal restrictions on future use of the code. Trac has adopted the [trac:TracLicense BSD 3-Clause license], and use of the same license in any plugin code is encouraged. One of the many benefits to adopting this license is that any plugin code can potentially be integrated into the Trac core down the road.
     11Trac-Hacks is an open source community driven by voluntary contributions and made successful by collaboration. Therefore we encourage the use of licenses that foster collaboration and minimise restrictions on future use of the code. Trac has adopted the [trac:TracLicense BSD 3-Clause license], and use of the same license in any plugin code is encouraged. One of the many benefits to adopting this license is that any plugin code can be integrated into the Trac core down the road.
    1112
    1213The following steps are suggested:
    … …  
    2223# you should have received as part of this distribution.
    2324}}}
    24  1. Add a license header to every RSS and XHTML Genshi template (example: TBD).
     25 1. Add a license header to every RSS and XHTML Genshi template (example: '''todo''').
    2526 {{{#!text/html
    2627<!--!
    … …  
    3233-->
    3334}}}
    34  The use of the XML comment marker as shown is important so that the text does not get rendered to the output. Make sure not to use the alternate form, which is rendered to the output as a hidden comment: `<!-- This is also a comment -->`
     35 The use of the XML comment marker as shown is important, so that the text does not get rendered to the output. Make sure not to use the alternate form, which is rendered to the output as a hidden comment: `<!-- This is also a comment -->`
    3536 1. Add a `COPYING` file with the license text in the top-level directory of the project ([browser:/plantumlmacro/trunk/COPYING example]).
    3637 1. Add an appropriate tag to the wiki page: [[ListTagged(realm:wiki license, format=compact)]]
    … …  
    4243== Metadata for Single-File Plugins
    4344
    44 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 its `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`).
     45Plugins are typically packaged using setuptools egg format, but Trac also supports single-file plugins. A single-file plugin 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 its `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`):
    4546
    4647{{{#!python
    4748revision = "$Rev$"
    48 homepage = "http://trac-hacks.org/wiki/MyAmazingMacro"
     49homepage = "http://trac-hacks.org/wiki/MyAmazingPlugin"
    4950license = "3-Clause BSD"
    50 author = "Guido van Rossum"
     51author = "Joe Bloggs"
    5152author_email = "trac@python.org"
    5253}}}
    … …  
    6667}}}
    6768
    68 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.
     69The 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.
    6970{{{#!sh
    7071svn propedit svn:keywords MyAmazingMacro.py
    … …  
    7879
    7980There are numerous other recommendations, and while some are mainly a matter of personal esthetic and preference, others are suggested for review and adoption:
    80  * [http://en.wikipedia.org/wiki/Yoda_conditions Yoda conditions] as [comment:ticket:11622:24 suggested by lkraav][[BR]]
    81  PROs:
     81 * [http://en.wikipedia.org/wiki/Yoda_conditions Yoda conditions] as [comment:ticket:11622:24 suggested by lkraav]:
    8282  * makes comparisons more obvious by putting the constant up-front
    8383  * erroneous assignment ('=' instead of '==') can't slip though unnoticed
    … …  
    8686not req.authname or req.authname == 'anonymous'
    8787 }}}
    88  same in 'Yoda condition' style
     88 The same example in 'Yoda condition' style:
    8989 {{{
    9090not req.authname or 'anonymous' == req.authname