Changes between Version 29 and Version 30 of DevGuide


Ignore:
Timestamp:
Sep 10, 2017, 11:25:49 AM (7 years ago)
Author:
figaro
Comment:

Further cosmetic changes

Legend:

Unmodified
Added
Removed
Modified
  • DevGuide

    v29 v30  
    4545== Metadata for Single-File Plugins
    4646
    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`):
     47Plugins 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`):
    4848
    4949{{{#!python
     
    7373
    7474There 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]):
    7676  * makes comparisons more obvious by putting the constant up-front
    77   * erroneous assignment ('=' instead of '==') can't slip though unnoticed
     77  * erroneous assignment ('=' instead of '==') can't slip through unnoticed
    7878 Example of common style:
    7979 {{{
     
    106106
    107107The 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.
     108It 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
     110If your plugin ships with other code, such as jQuery or a Python library, then mention this in your plugin description.
    110111
    111112== Publishing Packages to PyPI
    112113
    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].
     114There 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.
    114115
    1151161. [https://pypi.python.org/pypi?%3Aaction=register_form Register] yourself an account on PyPI.
    116 1. Install twine and add your credentials to `.pypirc` in your home directory. Example:
     1171. Install [pypi:twine] and add your credentials to `.pypirc` in your home directory. Example:
    117118{{{#!ini
    118119[distutils]
     
    131132password = mypassword
    132133}}}
    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 lessen 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`.
     1341. 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`.
    1341351. Update dependencies in your environment:
    135136{{{#!sh