Changes between Version 29 and Version 30 of DevGuide
- Timestamp:
- Sep 10, 2017, 11:25:49 AM (7 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
DevGuide
v29 v30 45 45 == Metadata for Single-File Plugins 46 46 47 Plugins 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`):47 Plugins 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 be added using file-scope attributes. The supported attributes and their aliases are: `author`, `author_email`, `home_page` (`url`), `license`, `trac` and `version` (`revision`): 48 48 49 49 {{{#!python … … 73 73 74 74 There are numerous other recommendations, and while some are mainly a matter of personal aesthetics and preference, others are suggested for review and adoption: 75 * [wikipedia:Yoda_conditions Yoda conditions] as [comment:ticket:11622:24 suggested by lkraav]:75 * [wikipedia:Yoda_conditions Yoda conditions] (see [comment:ticket:11622:24]): 76 76 * makes comparisons more obvious by putting the constant up-front 77 * erroneous assignment ('=' instead of '==') can't slip th ough unnoticed77 * erroneous assignment ('=' instead of '==') can't slip through unnoticed 78 78 Example of common style: 79 79 {{{ … … 106 106 107 107 The docstring for a Component class is displayed as the Component description on the plugin admin panel. 108 It is recommended that the description be prefixed with `[required]` or `[optional]`, to guide end-users in 109 enabling the proper Components. The `[extra]` descriptor can also used for features that have specialized or narrow use-cases. 108 It is recommended that the description be prefixed with `[required]` or `[optional]`, to guide end-users in enabling the proper Components. The `[extra]` descriptor can also be used for features that have specialized or narrow use-cases. 109 110 If your plugin ships with other code, such as jQuery or a Python library, then mention this in your plugin description. 110 111 111 112 == Publishing Packages to PyPI 112 113 113 There are no strict rules on how you should publish your packages to PyPI, but for those unfamiliar with the process we present some recommendations. Most Trac plugins contain only Python code and static assets, and therefore packages can be published in a platform and python-version independent wheel format. It is also recommended that you publish your package in the `sdist` (tarball) format. You can see a list of all Trac plugins that have been published to PyPI [https://pypi.python.org/pypi?:action=browse&show=all&c=516 here].114 There are no strict rules on how you should publish your packages to PyPI, but for those unfamiliar with the process we present some recommendations. Most Trac plugins contain only Python code and static assets, and therefore packages can be published in a platform and Python-version independent wheel format. It is also recommended that you publish your package in the `sdist` (tarball) format. There is also a [https://pypi.python.org/pypi?:action=browse&show=all&c=516 list of all Trac plugins] that have been published to PyPI. 114 115 115 116 1. [https://pypi.python.org/pypi?%3Aaction=register_form Register] yourself an account on PyPI. 116 1. Install twineand add your credentials to `.pypirc` in your home directory. Example:117 1. Install [pypi:twine] and add your credentials to `.pypirc` in your home directory. Example: 117 118 {{{#!ini 118 119 [distutils] … … 131 132 password = mypassword 132 133 }}} 133 1. Name your package appropriately. The package name is specified with the `name` argument in `setup.py`. It is recommend that you prefix your package name with `Trac`, for easy identification and to lessenthe likelihood of a package name collision with an existing PyPI package. For example, FullBlogPlugin is given the name `TracFullBlog`, and TagsPlugin is given the name `TracTags`.134 1. Name your package appropriately. The package name is specified with the `name` argument in `setup.py`. It is recommended that you prefix your package name with `Trac`, for easy identification and to reduce the likelihood of a package name collision with an existing PyPI package. For example, FullBlogPlugin is given the name `TracFullBlog`, and TagsPlugin is given the name `TracTags`. 134 135 1. Update dependencies in your environment: 135 136 {{{#!sh