Add add-on store conventions for manifest to developer guide#15888
Conversation
| - version (string): The version of this add-on; e.g. 2.0. (Mandatory) | ||
| - author (string): The author of this add-on, preferably in the form Full Name <email address>; e.g. Michael Curran <mick@kulgan.net>. (Mandatory) | ||
| - name (string, required): A short unique name for the add-on. | ||
| This is used to differentiate add-ons internally and is not shown to the user. |
There was a problem hiding this comment.
Can we also note that it is used when checking if the given add-on is in the store and can be updated? It may also be worth mentioning that if the name does not comply with the recommended standards, renaming an add-on for the store submission means that user is not offered updates if they have installed it externally previously, and should not be done.
There was a problem hiding this comment.
Isn't this case covered by the explanation that it is used to differentiate add-ons? A consequence of that would be a different add-on ID is treated as a different add-on.
There was a problem hiding this comment.
Since this targets developers perhaps this is indeed sufficient. If someone complains documentation can always be improved.
|
@XLTechie @CyrilleB79 - I think I have addressed all review comments now |
See test results for failed build of commit c9b1111e75 |
Co-authored-by: Luke Davis <8139760+XLTechie@users.noreply.github.com>
| - For a user to be able to update to this add-on, the version must be greater than the last version uploaded. | ||
| - Add-on versions are expected to be unique for the addon name and channel, meaning that a beta, stable and dev version of the same add-on cannot share a version number. | ||
| This is so there can be a unique ordering of newest to oldest. | ||
| - The suggested convention is to increment the patch version number for dev versions, increment the minor version number for beta versions, and increment the major version number for stable versions. |
There was a problem hiding this comment.
Sorry, still a remark; let me know if it should be discussed out of this PR though.
The suggested add-on versionning is still unclear to me.
What versions would you suggest for the following releases, all before 2024.1 stable release?
- First stable release of MyAddon, compatible with 2023.3 but not with 2024.1
- Dev release of MyAddon implementing compatibility with 2024.1 (including incompatible changes)
- Stable release on top of the first stable, containing a hotfix (e.g. due to external change such as new Windows update)
- Dev release on top of the last dev, containing the same hotfix.
There was a problem hiding this comment.
If you don't want to follow the conventions exactly, this should be fine, particularly if (2) is a major update to the add-on: 1.0.0, 2.0.0, 1.0.1, 2.0.1
However, I think the convention ordering might still be fine/better: 1.0.0, 1.0.1, 2.0.1, 2.0.2 or 1.0.0, 1.0.1, 2.0.0, 2.0.1
This ensures:
- (2) will not update to (3) without a user overriding compatibility
- (2) and (4) won't show up to users on 2023.3 if they have a minimum API version of 2024.1
- If all 4 releases have cross 2023.3/2024.1 compatibility, a user can be encouraged to update to each sequential version (e.g. (3) if (4) takes a while to be released).
There was a problem hiding this comment.
If you don't want to follow the conventions exactly, this should be fine, particularly if (2) is a major update to the add-on: 1.0.0, 2.0.0, 1.0.1, 2.0.1
However, I think the convention ordering might still be fine/better: 1.0.0, 1.0.1, 2.0.1, 2.0.2
This ensures:
* (2) will not update to (3) without a user overriding compatibility * (2) and (4) won't show up to users on 2023.3 if they have a minimum API version of 2024.1 * If all 4 releases have cross 2023.3/2024.1 compatibility, a user can be encouraged to update to each sequential version (e.g. (3) if (4) takes a while to be released).
OK. I understand now the recommended scheme: it's important to note that in the recommended scheme, the minor version number does not turn back to 0 when increasing the major version number. It would be nice to have an example since I had not it in mind and I do not know any current add-on following this scheme.
There was a problem hiding this comment.
Maybe this could be improved by saying version numbers can also be arbitrarily increased for "base" major addon update releases. e.g 1.x.x dev/beta/stable becomes 2.0.0 stable
There was a problem hiding this comment.
Also note that we will be able to abandon this convention for a simpler one, if we can include a patch number and a separate version display string
There was a problem hiding this comment.
@CyrilleB79, I try to follow this scheme in all my add-ons. Hope it"s well followed, unless some mistake from my part. You may search nvdaes in the store to see some examples, and if something is wrong I"ll try to fix it in the future, since my intention was allways to follow this convention for versions and channels.
Found while reviewing nvaccess/nvda#15888 Issue NVDA API version json file does not cover all existing NVDA versions. These ones minor versions are missing: 2018.4.1 2019.1.1 2019.2.1 2019.3.1 I doubt any add-on is impacted by these missing minor versions. But for completeness and clarity, it's better to have them covered. Solution Fix the description of API 0.0.0 so that 2018.4.1 is covered Added API for 2019.1.1 and 2019.2.1 Fixed description of 2019.3 to include also 2019.3.1. No API is added for this version since it contains only new translations; it is worth noting that this version is not listed in NVDA's change log.
Found while reviewing nvaccess/nvda#15888 Issue NVDA API version json file does not cover all existing NVDA versions. These ones minor versions are missing: 2018.4.1 2019.1.1 2019.2.1 2019.3.1 I doubt any add-on is impacted by these missing minor versions. But for completeness and clarity, it's better to have them covered. Solution Fix the description of API 0.0.0 so that 2018.4.1 is covered Added API for 2019.1.1 and 2019.2.1 Fixed description of 2019.3 to include also 2019.3.1. No API is added for this version since it contains only new translations; it is worth noting that this version is not listed in NVDA's change log.
Link to issue number:
None
Summary of the issue:
The add-on store adds additional requirements to manifest files for add-ons.
These should be explained in the developer guide.
Description of user facing changes