I'm skeptical about using $wgVersion for this.

For starters, it is deprecated, and the MW_VERSION constant should be used instead.

More importantly, though, I'm having trouble imagining a situation where the MediaWiki version would be useful as an API version. One of the main points of REST modules is specifically to give them independent versioning. Using the MediaWiki version seems almost guaranteed to be incorrect.

I'm not a huge fan of "v0", but if the linter will accept something like 0.1.0, I'd argue for that over MW_VERSION.

Notes from estimation:

• Ask Halley: Do We want to use mediawiki version? (it changes more often than we want to) ?

Hi friends,

My preference is that we don't use the MediaWiki version. In my opinion, API builders should be in control of if and how they want to increment the version on their specs, relative to what is changing within the module itself. I get the argument for using the MW version so that we don't end up in a situation where folks might forget to update the version, and/or to capture framework changes that may affect the spec, but it doesn't seem like it actually reflects the version of the API nor spec itself.

For now, let's keep the value manually set. We should throw errors if a version is not defined. In the case of the flat routes and as a full fallback option, let's use 0.1.0 for now, for the following reasons:

• The flat route spec is very much in flux, and it includes unversioned endpoints. Once we get to a point where the extension APIs and the like are fully broken out, we can probably bump up to v1 for the MW REST API.
• 0.1.0 makes sense (to me, feel free to disagree) in cases where it is not set at the module level, because it indicates instability with a side of "well, we are clearly generating a spec, so something exists" instead of just going with 0.0.0
  • If we go this route, I would also suggest/encourage that we increment the minor version as we create additional modules and remove things from the flat routes moving forward. Let me know if y'all disagree with that though.
• We can reasonably assume that all other modules include a version in the definition, and I assume we have tests in place to check and enforce that. If we do not have tests for that yet, we should include them in scope with conversations with Emeka next year.

Note for myself -- we should also probably have some documentation about how we expect people to use semantic versioning, in terms of when each value should be updated. I'll add it to our documentation list.

Change #1305757 had a related patch set uploaded (by Milazg; author: Milazg):

[mediawiki/core@master] REST: Add valid semver info.version for the default MediaWiki REST module

https://gerrit.wikimedia.org/r/1305757

Change #1305757 merged by jenkins-bot:

[mediawiki/core@master] REST: Add valid semver info.version for the default MediaWiki REST module

https://gerrit.wikimedia.org/r/1305757