Version number simplification for MV3 (mdn#21699)

rebloor · web-flow · commit e48162a69b02 · 2022-11-01T20:23:03.000+13:00
* Version number simplification for MV3

* Removed trailing spices

* Removed statement about beta version numbers in AMO

* Updates for feedback

* Fixed MD lint issues

* Feedback update and reorg

* Addressed MD lint issues

* Feedback related updates

* Feedback updates

* Rewording
diff --git a/files/en-us/mozilla/add-ons/webextensions/manifest.json/version/format/index.md b/files/en-us/mozilla/add-ons/webextensions/manifest.json/version/format/index.md
@@ -1,5 +1,5 @@
 ---
-title: Manifest Version Format
+title: Legacy Version Formats
 slug: Mozilla/Add-ons/WebExtensions/manifest.json/version/format
 tags:
   - Add-ons
@@ -9,39 +9,43 @@ tags:
 
 {{AddonSidebar}}
 
-A **version string** consists of one or more _version parts_, separated with dots.
+This page describes legacy web extension version string formats. See the manifest [version key](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/version) documentation for information on the current version string format.
 
-Each **version part** is itself parsed as a sequence of four parts: `<number-a><string-b><number-c><string-d>`. Each of the parts is optional. Numbers are integers base 10 (may be negative), strings are non-numeric ASCII characters.
+## Firefox legacy version number
 
-A few examples of valid version parts:
+A **version string** consists of one or more _version parts_, separated by dots.
+
+Each **version part** is parsed as a sequence of four parts: `<number-a><string-b><number-c><string-d>`. Each of the parts is optional. Numbers are integers base 10 (may be negative), and strings are non-numeric ASCII characters.
+
+Here are a few examples of valid version parts:
 
 - `0` (as in `1.0`): `<number-a>=0`
 - `5a` (as in `1.5a`): `<number-a>=5`, `<string-b>=a`
 - `5pre4` (as in `3.5pre4`): `<number-a>=5`, `<string-b>=pre`, `<number-c>=4`
 - `*` (as in `1.0.*`): `<string-b>=*`
 
-A few special parsing rules are applied for backwards compatibility and readability:
+A few special parsing rules are applied for backward compatibility and readability:
 
 - if the version part is a single asterisk, it is interpreted as an infinitely-large number:
   `1.5.0.*` is the same as `1.5.0.(infinity)`
 - if string-b is a plus sign, number-a is incremented to be compatible with the Firefox 1.0.x version format:
   `1.0+` is the same as `1.1pre`
 
-The rationale behind splitting a version part into a sequence of strings and numbers is that when comparing version parts, the numeric parts are compared as numbers, e.g. '1.0pre1' < '1.0pre10', while the strings are compared bytewise. See the next section for details on how versions are compared.
+The rationale behind splitting a version part into a sequence of strings and numbers is that when comparing version parts, the numeric parts are compared as numbers, for example, '1.0pre1' < '1.0pre10', while the strings are compared byte-wise. See the next section for details on how versions are compared.
 
-See [maintenance policy](https://extensionworkshop.com/documentation/publish/signing-and-distribution-overview/#distributing-your-addon) for special rules that mark version as "beta" in the AMO queues.
+From Firefox 108, web extensions using this version string trigger a warning on installation.
 
 ## Comparing versions
 
 When two version strings are compared, their version parts are compared left to right. An empty or missing version part is equivalent to `0`.
 
-If at some point a version part of one version string is greater than the corresponding version part of another version string, then the first version string is greater than the other one.
+If at some point, a version part of one version string is greater than the corresponding version part of another version string, then the first version string is greater than the other one.
 
-Otherwise, the version strings are equal. Note that since missing version parts are treated as if they were `0`, the following version strings are equal: `1`, `1.0`, `1.0.`, `1.0.0`, and even `1.0..`.
+Otherwise, the version strings are equal. As missing version parts are treated as if they were `0`, these version strings are equal: `1`, `1.0`, `1.0.`, `1.0.0`, and even `1.0..`.
 
 ### Comparing version parts
 
-Version parts are also compared left to right, parts A and C are compared as numbers, while parts B and D are compared byte-wise. A string-part that exists is always less than a string-part that doesn't exist (`1.6a` is less than `1.6`).
+Version parts are also compared left to right; parts A and C are compared as numbers, while parts B and D are compared byte-wise. A string part that exists is always less than a string part that doesn't exist (`1.6a` is less than `1.6`).
 
 ## Examples
 
diff --git a/files/en-us/mozilla/add-ons/webextensions/manifest.json/version/index.md b/files/en-us/mozilla/add-ons/webextensions/manifest.json/version/index.md
@@ -27,34 +27,47 @@ browser-compat: webextensions.manifest.version
   </tbody>
 </table>
 
-Version of the extension, formatted as numbers and ASCII characters separated by dots. For the details of the version format, see the [Version format](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/version/format) page.
+The **version string** for the extension.
 
-You can inspect the [add-ons linter code](https://github.com/mozilla/addons-linter/blob/master/src/schema/formats.js#L10) to see how extension versions for Firefox are validated.
+## Version format
 
-Note that [the syntax defined for Chrome's `version`](https://developer.chrome.com/docs/extensions/mv3/manifest/version/) is more restrictive than that used by Firefox:
+The version string consists of 1 to 4 numbers separated by dots, for example, `1.2.3.4`. Non-zero numbers must not include a leading zero. For example, `2.01` is not allowed; however, `0.2`, `2.0.1`, and `2.10` are allowed.
 
-- values for `version` that are valid for Chrome will always be valid for Firefox
-- values for `version` that are valid for Firefox may not be valid for Chrome
+Extension stores and browsers may enforce or warn if the version string doesn't comply with this format. They may also apply restrictions to the range of numbers available. For example:
 
-To obtain your extension version in your JavaScript code, use:
+- [addons.mozilla.org](https://addons.mozilla.org/) (AMO) allows version strings using numbers of up to nine digits, complying with this regular expression `^(0|[1-9][0-9]{0,8})([.](0|[1-9][0-9]{0,8})){0,3}$`. Also, from Firefox 108, a warning is provided if an extension is installed with a version number that doesn't match this format.
+- The Chrome Web Store requires [numbers between 0 and 65535](https://developer.chrome.com/docs/extensions/mv3/manifest/version/) and does not permit all-zero extension strings. For example, 0.0 or 0.0.0.0 are not permitted.
+
+It may be possible to create an extension that appears to have a valid version number when run in a browser but doesn't comply with store requirements. Particular care should be taken when developing cross-browser extensions that use large number elements.
+
+Some browsers and web stores may recognize the [version_name](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/version_name) key. This key enables you to provide a descriptive version string that may be displayed instead of the version number. For example, `1.0 beta`.
+
+### Comparing versions
+
+To determine which of two extension versions is the most recent, the version string numbers are compared left to right. A missing version string element is equivalent to `0`. For example, 1.0 is equivalent to 1.0.0.0. The first version string with a number greater than the corresponding number in the other version string is the most recent. For example, 1.10 is a more recent version than 1.9.
+
+## Legacy version formats
+
+See [Legacy version formats](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/version/format) for details of previously supported version strings.
+
+## Access the version number in code
+
+You obtain the extension version in your JavaScript code using:
 
 ```js
 console.log(browser.runtime.getManifest().version);
 ```
 
-## Example
-
 If the manifest contains:
 
 ```json
 "version": "0.1"
 ```
 
-To obtain your extension version in your JavaScript code, use:
+You see this in the console log:
 
-```js
-console.log(browser.runtime.getManifest().version);
-// expected output: "0.1"
+```text
+"0.1"
 ```
 
 ## Browser compatibility
diff --git a/files/en-us/mozilla/firefox/releases/108/index.md b/files/en-us/mozilla/firefox/releases/108/index.md
@@ -54,6 +54,8 @@ This article provides information about the changes in Firefox 108 that will aff
 
 ## Changes for add-on developers
 
+- Firefox now issues a warning when an extension is installed if its [version number](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/version) doesn't follow the recommended format ({{bug(1793925)}}).
+
 ### Removals
 
 ### Other
