Changes between Version 34 and Version 35 of DevGuide


Ignore:
Timestamp:
Apr 15, 2021, 12:23:36 PM (14 months ago)
Author:
figaro
Comment:

Cosmetic changes

Legend:

Unmodified
Added
Removed
Modified
  • DevGuide

    v34 v35  
    3939 1. Add an appropriate tag to the wiki page: [[ListTagged(realm:wiki license, format=compact)]]
    4040
    41 Additional tags can be created for additional or more descriptive license types.
     41New tags can be added for more descriptive license types.
    4242
    43 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).
     43Currently it is not recommended to add license text to static resources (ie file in `htdocs`), since doing so increases 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).
    4444
    4545== Metadata for Single-File Plugins
     
    7474== Assert Minimum Trac Version Requirement
    7575
    76 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 during installation of a plugin. The result can be an unintended upgrade of a user's installation (#10607).
     76A 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 may cause issues, some of which are documented in #9800, and is not recommended. One of the more severe consequences is that setuptools may download and install a newer version of Trac during installation of a plugin and the result can be an unintended upgrade of a user's installation (#10607).
    7777
    7878A better approach is to place the following in the package `__init__.py`, modifying `min_trac_version` as appropriate for your plugin:
     
    9797If your plugin ships with other code, such as jQuery or a Python library, then mention this in your plugin description.
    9898
    99 == Version of your plugin
     99== Plugin version identification
    100100
    101 You should use the {{{major.minor.micro}}} semantic versioning scheme also used by [trac:TracDev/ReleaseChecklist#Versionidentification Trac (version identification)]. ​Some additional guidance can be found in PEP:0440.
     101You should use the {{{major.minor.micro}}} semantic versioning scheme for Trac plugins as also used by [trac:TracDev/ReleaseChecklist#Versionidentification Trac (version identification)]. ​Some additional guidance can be found in PEP:0440.
    102102
    103103In the event that a defect or packaging distribution error is discovered after a release is made, the ''micro'' version number should be incremented and a new minor release created. Note that a filename cannot be reused when uploading to PyPI ​more than once, so the ''micro'' version must also be incremented in the event of a packaging or uploading error.
    104104
    105 Development releases are created directly from the current source. These are not uploaded to PyPI and usually done by the user to get the latest snapshot. To distinguish them from final releases a {{{dev}}} suffix should be added. This can be done for you by creating a {{{setup.cfg}}} file in the same directory where {{{setup.py}}} is located with the following contents.
     105Development releases are created directly from the current source. These are not uploaded to PyPI and usually done by the user to get the latest snapshot. To distinguish them from final releases a {{{dev}}} suffix should be added. This can be done for you by creating a {{{setup.cfg}}} file in the same directory where {{{setup.py}}} is located with the following content:
    106106{{{#!ini
    107107[egg_info]
     
    110110
    111111=== Development cycle
    112 The proposed development and release cycle is described here. The current final version is {{{1.0.1}}}. The next planned release version is {{{1.2.0}}}.
     112
     113The development and release cycle of plugins also adheres to standards. In the following examples the current final version of a plugin is {{{1.0.1}}} and the next planned release version is {{{1.2.0}}}.
    113114
    1141151. In {{{setup.py}}} specify the next version:
    115116   {{{#!python
    116117setup(
    117     name='YourPluginsName',
    118     version='1.2.0',
     118    name = 'YourPluginsName',
     119    version = '1.2.0',
    119120[...]
    120121     )
     
    126127   }}}
    127128
    128 You may proceed with development now. Whenever a user is creating his own development release it will be marked like {{{YourPluginName-1.2.0.dev0-py3.8.egg}}}.
     129When consequently a plugin is further developed, then the development release should be labeled as {{{YourPluginName-1.2.0.dev0-py3.8.egg}}}. So when creating a release do the following:
    129130
    130 When creating a release do the following:
    1311311. Temporarily remove the entry from {{{setup.cfg}}}:
    132132   {{{#!ini
     
    134134#tag_build = dev
    135135   }}}
    136 1. Create a release version which will be named like {{{YourPluginName-1.2.0-py3.8.egg}}}. If you want to publish to PyPI see the Instructions below.
     1361. Create a release version which will be named like {{{YourPluginName-1.2.0-py3.8.egg}}}. If you also want to publish to PyPI, then see the Instructions below.
    1371371. After publishing the release version prepare the next development cycle by increasing the version number in {{{setup.py}}} and putting back the development tag in {{{setup.cfg}}}:
    138138   {{{#!python
    139139setup(
    140     name='YourPluginsName',
     140    name = 'YourPluginsName',
    141141    # Note that the version number was changed from 1.2.0 to 1.3.0
    142142    # which will be the next release.
    143     version='1.3.0',
     143    version = '1.3.0',
    144144[...]
    145145     )
     
    181181$ python setup.py sdist bdist_wheel
    182182}}}
    183 1. Publish your packages.
     1831. Publish your packages:
    184184{{{#!sh
    185185$ pip install -U twine
     
    187187}}}
    188188
    189 Some thing to be aware of:
     189Some things to be aware of:
    190190* Once a package is published to PyPI the package cannot be republished without changing the package version. You can simply bump the version or add a [PEP:0440/#implicit-post-release-number post release number].
    191 * You may wish to first publish to `pypi-test`, particularly if you aren't familiar with the process. Once you establish that the package can be installed from pypi-test, you can publish to pypi. Note that you have to [https://testpypi.python.org/pypi?%3Aaction=register_form register] separately for pypi-test, and specify the server name in `twine` commands.
     191* You may wish to first publish to `pypi-test`, particularly if you aren't familiar with the process. Once you establish that the package can be installed from pypi-test, you can publish to PyPI. Note that you have to [https://testpypi.python.org/pypi?%3Aaction=register_form register] separately for pypi-test, and specify the server name in `twine` commands:
    192192{{{#!sh
    193193$ twine upload dist/*.whl dist/*.tar.gz pypi-test
    194194}}}
    195 * Once you take ownership of a package name on PyPI there is no process for transferring ownership of the package that can happen independent of you (see PEP:0541). This is a frequent cause of abandoned packages on PyPI, where the original owner is not reachable and a new maintainer of the package cannot update the published package. For that reason, please consider giving ownership of the package to other users in case you someday decide to no longer maintain the package.  For example, you could give ownership to the [TracHacks#Who TracHacks admins].
     195* Once you take ownership of a package name on PyPI there is no process for transferring ownership of the package that can happen independent of you (see PEP:0541). This is a frequent cause of abandoned packages on PyPI, where the original owner is not reachable and a new maintainer of the package cannot update the published package. For that reason, please consider giving ownership of the package to other users in case you someday decide to no longer maintain the package. For example, you could give ownership to the [TracHacks#Who TracHacks admins].
    196196
    197197Further reading: