Always use .0 in the version number.
For the Python API docs, I left out _0 and _release postfix entirely, with the assumption that bugfix releases can share the same Python API docs. This is debatable, but I don't think there has ever been a significant difference between them. Also is consistent with the Blender manual, and keeps the same link working.
Generally looks fine.
Think I agree, PY API should never change in bugfix releases (there can be some exceptions of course, but even then people are assumed to be using latest bugfix release anyway).
Note however that this is a change compared to current situation (corrective releases have their own version of doc currently).
There is another point related to version that I do not see addressed here though (unless I missed it): add-ons. Those can define a minimum compatibility version, which is very useful when they are making use of an API that did not exist before (see e.g. FBX, where I recently had to update minimal version to latest in master after adding some feature to our PY API that made importing animation twice faster).
So far we have been using file subversion for this, and I think we should keep doing so, since we now explicitly expect Blender subversion itself to not affect API...
Right now it uses (in PREFERENCES_OT_addon_enable e.g.) bpy.app.version, which would not work properly imho. I would suggest exposing the blend file subversion number to python as well, in a bpy.app.blendfile_version field e.g.? And use that one instead to compare against bl_info.blender numbers.
This comment is not correct anymore, we have no way to distinguish between release and non-release numbering here.
I mentioned it in T76058, but did not notice that compatibility check in PREFERENCES_OT_addon_enable.
Still I'd rather stop using the file subversion here. The subversion number mentioned in the error message will not mean anything to users. And it's not going to be clear to add-on authors that the number they are supposed to specify there would be a different one than the number displayed in the UI. A note about this in the Python API docs would be missed by most.
For bundled add-ons the version number is not important, and probably it's wrong in many cases. For external addons it can help, but it's not clear to me this is something they rely on much.
The problem is that there is no other way currently to handle this issue… I remember raising the topic of having proper API version number too at some point during 2.80 dev process (which would then be disconnected from blendfile version, and now blender version), but nobody else seemed to find it important/needed, and so we sticked to blendfile subversion system.
If we go with this patch, things will get even worse, as there will be basically no way to check whether an add-on can work with a given random build of blender. Maybe we can live with that, but I really think we should have a better way to deal with this issue.
Think this comment can be removed altogether in fact… It's indeed completely wrong and irrelevant, and quiet useless too.
In my opinion there is not much point in providing an API version for an alpha version of Blender. We don't guarantee any kind of API stability for such versions. I personally don't think this is an issue to be solved.
We could easily add a bpy.app.api_version with the subversion, and then still decide internally if we want to tie that to the file subversion or not. I'd rather not have the concept at all, but if @Campbell Barton (campbellbarton) also thinks it's needed I can add it.