Add-on template and update channel definition: updates, a word about update channel definition


Hi all,


Prompted by a discussion on nvda-devel list between Luke Davis and I regarding clarity of update channel definition, coupled with a report from Brian Gaff about some add-ons shipping with update channel set to “stable” for stable releases, I decided to take a look at add-on template repo and make the following change:


Update channel definition for build vars dictionary: it’ll say:


Add-on update channel (default is None, denoting stable releases, and for development releases, use "dev"; do not change unless you know what you are doing)


This should clarify the overall purpose of that manifest key, meaning of “None”, and remind you not to change it unless you are releasing something other than stable releases (i.e. know what you are doing). For the purposes of the template and add-on update checks (currently performed by Add-on Updater, and one day, by NVDA itself unless the scheme changes), setting update channel to None means this is a stable release. Many of you should leave it at default value of None unless you wish to publish development snapshots or need to maintain channels in addition to stable (and/or dev).


You might be asking, why None for stable channel? For some of you, this is a repeat, so please bear with me:


In 2012, NV Access, together with some contributors, formally defined and implemented NVDA add-on management facility. Prior to NvDA 2012.2, people wishing to extend NVDA would write Python modules and would place them in now deprecated plugin directories (appModules, globalPlugins, brailleDisplayDrivers, synthDrivers inside NVDA user directory). The add-ons subsystem was an attempt to let plugin writers, now commonly known as add-on authors, to package modules inside a compressed (zip) file with an .nvda-addon extension, and once opened by NVDA, add-on packages will be extracted to the newly created “addons” folder inside dedicated subfolders (named according to the add-on name/ID defined in the manifest).


In an attempt to coordinate add-on development and collect add-ons from the community and showcase them under one roof, in 2013, the add-ons community mailing list (first generation on was formed, along with the opening of the NVDA community add-ons website ( The backbone of the community add-ons website is hosted on an add-on files repository (Bitbucket) in the form of a PHP file that records add-ons hosted on the website and download links for them. When an add-on is approved for community add-ons website, a unique shorthand key was generated (or rather, created) for the add-on and added to the database. Back then, most add-ons were listed as stable versions (with some of them going through development builds), hence the key itself without qualifiers denote stable releases. Subsequently, once the add-on review process was formalized in 2015, more add-ons started using the “-dev” suffix to denote add-ons under development. This process continues today even with the add-ons mailing list moving to Groups.IO in recent years.


Then around this time last year (2018), I released Add-on Updater, powered by standalone update facility from StationPlaylist and Windows 10 App Essentials. Borrowing the conventions from many years, this add-on treats add-on keys without qualifiers as stable releases. The add-on contains a map of add-on ID’s to shorthand keys used to look up add-on download links/versions from the add-ons website.


The add-on would then calculate the “update channel” value as follows:


  1. If an add-on does not define an update channel in the manifest (old add-ons), it is treated as a stable channel. This check is becoming rare.
  2. If the update channel is defined as “None” (technically, it should be None, but ConfigObj turns this into a string), it is a stable channel.
  3. If a different update channel is defined, a qualifier is recorded. Technically, stable channel does have a qualifier, but it is nothing.
  4. Depending on channel obtained, the update channel value (to be passed to a function/thread responsible for connecting to the website and retrieving add-on update information) is either the shorthand key (stable release) or shorthand key + “-“ (hyphen) followed by the name of the custom channel. This is a necessary work because that is how add-on download links are recorded on the website.


For example, for Enhanced Touch Gestures, if you are checking for stable releases, the shorthand key (“ets”) alone will be the update channel value; if you are looking for development releases, the value becomes “ets-dev”. Or perhaps I release a custom build of Enhanced Touch Gestures, say “alpha”. The value then becomes “ets-alpha”.


So far, it is going well. However, it falls apart when trying to retrieve update information for some add-ons: due to ambiguity present in current add-on template (my sincerest apologies), some authors defined “stable” for stable releases when it should not be defined as such. For example, Toolbars Explorer defines “stable” for stable releases, which means instead of looking at “tbx”, it will actually look up “tbx-stable” which actually doesn’t exist. This is the reason why some of you could not obtain latest stable releases for add-ons like Toolbars Explorer, hence the correction and advice noted above.


I will push necessary changes to add-on template tonight.


Because it takes time to update all affected add-ons to change their stable channel definitions (coupled with Python 3 porting work), I will not enforce stable release definition change today: I will give you 30 days (until September 10, 2019) to update add-ons. September 10th will also be the day I will release Add-on Updater 19.09 (the second mandatory update for everyone), which will enforce this change; the next version of this add-on, version 19.08.1 scheduled shortly after NVDA 2019.2 stable version is released, will include a compatibility workaround for add-ons affected by stable channel definition problem (note that 19.08.1 will require NVDA 2019.2 due to maintenance policy for Add-on Updater).


A huge caveat: the update channel scheme may change once NVDA starts checking for add-on updates on its own (the missing puzzle pieces are server-side work and data exchange mechanisms; others such as update check client and the user interface are done).


Thanks, and again, my sincerest apologies for causing ambiguities in the first place and for causing an inconvenience.



Join to automatically receive all group messages.