Changes between Version 18 and Version 19 of DevGuide
- Timestamp:
- Dec 8, 2015, 2:25:53 PM (8 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
DevGuide
v18 v19 3 3 = Plugin Development Guide 4 4 5 This 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].5 This page documents 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]. 6 6 7 7 == Licensing 8 8 9 Plugin 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.9 Plugin authors are encouraged to clearly indicate how the contribution is licensed. This is important for both users and future developers of your plugin, because if you choose to no longer support the plugin, the terms under which someone else can adopt and develop it are clear. 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. 10 10 11 11 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 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. 12 12 13 The following steps are suggested :13 The following steps are suggested to add a license: 14 14 1. Add the `license` keyword in `setup.py` ([browser:/plantumlmacro/trunk/setup.py@11477:22 example]). 15 15 1. Add a license header to every Python source file ([browser:/plantumlmacro/trunk/plantuml/macro.py@11477:1-9 example]). … … 39 39 Additional tags can be created for additional or more descriptive license types. 40 40 41 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).41 Currently it is not recommended to add license text to static resources (ie 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). 42 42 43 43 == Metadata for Single-File Plugins … … 72 72 }}} 73 73 74 Ke ep 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.74 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. 75 75 76 76 == Coding Style … … 79 79 80 80 There are numerous other recommendations, and while some are mainly a matter of personal esthetic and preference, others are suggested for review and adoption: 81 * [ http://en.wikipedia.org/wiki/Yoda_conditions Yoda conditions] as [comment:ticket:11622:24 suggested by lkraav]:81 * [wikipedia:Yoda_conditions Yoda conditions] as [comment:ticket:11622:24 suggested by lkraav]: 82 82 * makes comparisons more obvious by putting the constant up-front 83 83 * erroneous assignment ('=' instead of '==') can't slip though unnoticed … … 85 85 {{{ 86 86 not req.authname or req.authname == 'anonymous' 87 87 }}} 88 88 The same example in 'Yoda condition' style: 89 89 {{{ 90 90 not req.authname or 'anonymous' == req.authname 91 91 }}} 92 92 93 93 == Assert Minimum Trac Version Requirement 94 94 95 The most common method of specifying a minimum required Trac version is to add an installation requirement in `setup.py`. For example: `install_requires = ['Trac >= 0.12']`. This causes numerous problems, some of which are documented in #9800, and is not recommended. One of the most negative consequences is that setuptools may download and install a newer version of Trac. The result can be an unintended upgrade of a user's installation (#10607).95 A common method of specifying a minimum required Trac version is to add an installation requirement in `setup.py`. For example: `install_requires = ['Trac >= 0.12']`. However, this causes numerous problems, some of which are documented in #9800, and is not recommended. One of the most negative consequences is that setuptools may download and install a newer version of Trac. The result can be an unintended upgrade of a user's installation (#10607). 96 96 97 97 A better approach is to place the following in the package `__init__.py`, modifying `min_trac_version` as appropriate for your plugin:
