Describe versioning of plugins on DevGuide page

[Cinc-th]

There is no guide for setting the version of a plugin so one can see different variations:

• x.y
• x.y.z
• x.ydev
• ...

Todo

There should be some guidance on the DevGuide page regarding versioning. This should include instructions how to use the dev tag in versions.

[Ryan J Ollos]

Some subset of ​TracDev/ReleaseChecklist may be useful to copy.

[Cinc-th]

I came up with the following. If this is nice enough I'll change the DevGuide page accordingly.

---

Version of your plugin

You should use the major.minor.micro semantic versioning scheme also used by ​Trac (version identification). ​Some additional guidance can be found in ​PEP:0440.

In 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.

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.

[egg_info]
tag_build = dev

Development cycle

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.

1. In setup.py specify the next version:

   setup(
       name='YourPluginsName',
       version='1.2.0',
   [...]
        )
   

2. in setup.cfg add the development tag as described before:

   [egg_info]
   tag_build = dev
   

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.

When creating a release do the following:

1. Temporarily remove the entry from setup.cfg:

   #[egg_info]
   #tag_build = dev
   

2. 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.
3. 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:

   setup(
       name='YourPluginsName',
       # Note that the version number was changed from 1.2.0 to 1.3.0
       # which will be the next release.
       version='1.3.0',
   [...]
        )
   

   [egg_info]
   tag_build = dev
   

[Cinc-th]

Typo police...

[Ryan J Ollos]

Looks good to me.

[Cinc-th]

Added descriptions of the development cycle and how to chose a plugins version to DevGuide@version 34.