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

Brian's Mail list account

Hi, yes this explains why I can get toolbars Explorer going myself via a modified file but the official fixed version loads in some versions of nvda but not in others even though its flagged as downloadable.
It may also go some way to define my issues in retro creating an add on by just updating the source in the add on and the versions in the manifest. I had not appreciated the power of the channel defining item.

One other thing. Has the Alpha snap had its auto update disabled? I only seem to find updates manually, even though the checkbox is checked for auto updates. The beta and RC still work.
One other thing I have noticed that can cause problems is that if people are doing what I did and modifying the code for the add on source and the manifest in situe for alpha snaps, make sure any of the compiled files are removed before you restart nvda to test it. I have no idea why this makes a difference but it seems Python 3 makes a new sub directory for the compiled code and does not delete the old compiled Python 2 code.


Sent via blueyonder.
Please address personal E-mail to:-
briang1@..., putting 'Brian Gaff'
in the display name field.
Newsgroup monitored: alt.comp.blind-users

----- Original Message -----
From: "Joseph Lee" <@joslee>
To: <>
Sent: Sunday, August 11, 2019 4:38 AM
Subject: [nvda-devel] 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

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.