Topics

Guidance For New Add-on Creator

Jim Homme
 

Hi,
Two questions. First, is the guidance at https://github.com/nvdaaddons/nvdaaddons.github.io/wiki still relevant? Second, what is an add-on I can model my first one after that follows the community-accepted guidelines?
 
Thanks.
Jim H
 
 
==========
Jim Homme
Digital Accessibility
Bender Consulting Services
412-787-8567
 
 
 

Luke Davis
 

On Tue, 23 Jun 2020, Jim Homme wrote:

Two questions. First, is the guidance at https://github.com/nvdaaddons/nvdaaddons.github.io/wiki still relevant?
I think Nolea may have to address that, although i believe that much of it is.

However, you should (also) be looking at these:

NVDA Developer Guide: https://www.nvaccess.org/files/nvda/documentation/developerGuide.html
NVDA Add-on Development Guide: https://github.com/nvdaaddons/devguide/wiki/NVDA%20Add-on%20Development%20Guide

Second, what is an add-on I can model my
first one after that follows the community-accepted guidelines?
That depends on what your add-on is trying to do.
Add-ons are written very differently depending on what they are supposed to accomplish.

Some have multiple python files, some have only one.
Some use config screens, some don't.
Some are global plugins, others are app modules.

What do you want your first add-on to be and do, in general?

For an example of the only one of mine I have made publicly available to date, look at https://github.com/XLTechie/debugHelper

You will see examples of an NVDA settings config window, use of the log, use of global variables, and probably a few other concepts.
The python portion is only 142 lines.

For better, and bigger/more diverse, examples, Joseph Lee's add-ons are usually a very good source. https://github.com/josephsl

Regards,

Luke

Noelia Ruiz
 

Hi, I agree with Luke.
For the question about wiki, it contains articles valid for reference,
though some of them are not applicable now, until NV Access can work
fixing and, if needed, translating the system:
https://github.com/nvdaaddons/nvdaaddons.github.io/wiki/MakeAddonsTranslatable

Repos document hasn't been widely adopted: not many authors have
requested to add their repos to this document for reference, and it
hasn't been set as a requirement or suggestion most times, so it isn't
used in all its potential:

https://github.com/nvdaaddons/nvdaaddons.github.io/wiki/repos

Appveyor, GitHub Actions and GitHub webhooks are still valid for me. I
prefer to use GitHub Actions and GitHub webhooks to send emails to a
possible add-ons mailing list for commits, who was broken in Bitbucket
but that Mesar managed long time ago, was used at least by Abdel and
me, but I'm not sure if it could be replaced by a simpler solution
with GitHub Actions. I'm waiting for NV Access and stopped working on
add-ons until the system works well again, so I haven't investigated
this.
- Guidelines is a document originally created by Mesar, and I think it
should be reviewed including linting features and modifying the part
relative to appropiate add-on names. For instance, it's recommended
that add-on names don't include the word add-on, since it is redundant
in most cases, but for example it is perfectly appropiate for add-on
updater by Joseph.
- Add-on workflow is a document created by Mesar as a proposal, though
it's not applied.

About add-ons following guidelines, I think it's good to read them,
but it's difficult to follow models for this. They talk about code
style, release frequency, consult other add-ons and NVDA commands to
minimize conflicts, etc.

Cheers


2020-06-23 23:56 GMT+02:00, Luke Davis <luke@...>:

On Tue, 23 Jun 2020, Jim Homme wrote:

Two questions. First, is the guidance at
https://github.com/nvdaaddons/nvdaaddons.github.io/wiki still relevant?
I think Nolea may have to address that, although i believe that much of it
is.

However, you should (also) be looking at these:

NVDA Developer Guide:
https://www.nvaccess.org/files/nvda/documentation/developerGuide.html
NVDA Add-on Development Guide:
https://github.com/nvdaaddons/devguide/wiki/NVDA%20Add-on%20Development%20Guide

Second, what is an add-on I can model my
first one after that follows the community-accepted guidelines?
That depends on what your add-on is trying to do.
Add-ons are written very differently depending on what they are supposed to

accomplish.

Some have multiple python files, some have only one.
Some use config screens, some don't.
Some are global plugins, others are app modules.

What do you want your first add-on to be and do, in general?

For an example of the only one of mine I have made publicly available to
date,
look at https://github.com/XLTechie/debugHelper

You will see examples of an NVDA settings config window, use of the log, use
of
global variables, and probably a few other concepts.
The python portion is only 142 lines.

For better, and bigger/more diverse, examples, Joseph Lee's add-ons are
usually
a very good source.
https://github.com/josephsl

Regards,

Luke



Noelia Ruiz
 

Sorry, about add-on names, the word add-on is not mentioned, just this:

2. Addon name should not contain "nvda", "plugin", "appmodule",
"globalPlugin" as part of its name, the user should not have to worry
about implementational issues.

Just to clarify :)
Anyway there are add-ons like Kill NVDA, which may need some of these words.




2020-06-24 6:08 GMT+02:00, Noelia Ruiz via groups.io
<nrm1977=gmail.com@groups.io>:

Hi, I agree with Luke.
For the question about wiki, it contains articles valid for reference,
though some of them are not applicable now, until NV Access can work
fixing and, if needed, translating the system:
https://github.com/nvdaaddons/nvdaaddons.github.io/wiki/MakeAddonsTranslatable

Repos document hasn't been widely adopted: not many authors have
requested to add their repos to this document for reference, and it
hasn't been set as a requirement or suggestion most times, so it isn't
used in all its potential:

https://github.com/nvdaaddons/nvdaaddons.github.io/wiki/repos

Appveyor, GitHub Actions and GitHub webhooks are still valid for me. I
prefer to use GitHub Actions and GitHub webhooks to send emails to a
possible add-ons mailing list for commits, who was broken in Bitbucket
but that Mesar managed long time ago, was used at least by Abdel and
me, but I'm not sure if it could be replaced by a simpler solution
with GitHub Actions. I'm waiting for NV Access and stopped working on
add-ons until the system works well again, so I haven't investigated
this.
- Guidelines is a document originally created by Mesar, and I think it
should be reviewed including linting features and modifying the part
relative to appropiate add-on names. For instance, it's recommended
that add-on names don't include the word add-on, since it is redundant
in most cases, but for example it is perfectly appropiate for add-on
updater by Joseph.
- Add-on workflow is a document created by Mesar as a proposal, though
it's not applied.

About add-ons following guidelines, I think it's good to read them,
but it's difficult to follow models for this. They talk about code
style, release frequency, consult other add-ons and NVDA commands to
minimize conflicts, etc.

Cheers


2020-06-23 23:56 GMT+02:00, Luke Davis <luke@...>:
On Tue, 23 Jun 2020, Jim Homme wrote:

Two questions. First, is the guidance at
https://github.com/nvdaaddons/nvdaaddons.github.io/wiki still relevant?
I think Nolea may have to address that, although i believe that much of
it
is.

However, you should (also) be looking at these:

NVDA Developer Guide:
https://www.nvaccess.org/files/nvda/documentation/developerGuide.html
NVDA Add-on Development Guide:
https://github.com/nvdaaddons/devguide/wiki/NVDA%20Add-on%20Development%20Guide

Second, what is an add-on I can model my
first one after that follows the community-accepted guidelines?
That depends on what your add-on is trying to do.
Add-ons are written very differently depending on what they are supposed
to

accomplish.

Some have multiple python files, some have only one.
Some use config screens, some don't.
Some are global plugins, others are app modules.

What do you want your first add-on to be and do, in general?

For an example of the only one of mine I have made publicly available to
date,
look at https://github.com/XLTechie/debugHelper

You will see examples of an NVDA settings config window, use of the log,
use
of
global variables, and probably a few other concepts.
The python portion is only 142 lines.

For better, and bigger/more diverse, examples, Joseph Lee's add-ons are
usually
a very good source.
https://github.com/josephsl

Regards,

Luke





Luke Davis
 

Well, in general though, personally I would agree that the word "addon" or "add-on" probably shouldn't be in the name either.

But there are some cases where there is a good reason to do this, such as "Add-on Updater". "Updater" could refer to anything, but "Add-on Updater" makes it clear what it updates.

The same is true for "NVDA Killer": it could kill anything, and needs the clarity, but usually this would be redundant.

So it's just a matter of following common sense.

Like Noelia wrote in her other message:

"but it's difficult to follow models for this. They talk about code
style, release frequency, consult other add-ons and NVDA commands to
minimize conflicts, etc.
"

Which is exactly right. There are two many ways to do things. There may be accepted ways of performing certain tasks in an add-on, and work that has already been done that you can copy. But it's very hard to say "do it exactly this way", without writing the add-on for someone. So all that can be given are best practices most of the time.

And if you submit your add-on for review, the reviewers will probably tell you if you've done something crazy.

Luke

Noelia wrote:

Sorry, about add-on names, the word add-on is not mentioned, just this:

2. Addon name should not contain "nvda", "plugin", "appmodule",
"globalPlugin" as part of its name, the user should not have to worry
about implementational issues.

Just to clarify :)
Anyway there are add-ons like Kill NVDA, which may need some of these words.




2020-06-24 6:08 GMT+02:00, Noelia Ruiz via groups.io
<nrm1977=gmail.com@groups.io>:
Hi, I agree with Luke.
For the question about wiki, it contains articles valid for reference,
though some of them are not applicable now, until NV Access can work
fixing and, if needed, translating the system:
https://github.com/nvdaaddons/nvdaaddons.github.io/wiki/MakeAddonsTranslatable

Repos document hasn't been widely adopted: not many authors have
requested to add their repos to this document for reference, and it
hasn't been set as a requirement or suggestion most times, so it isn't
used in all its potential:

https://github.com/nvdaaddons/nvdaaddons.github.io/wiki/repos

Appveyor, GitHub Actions and GitHub webhooks are still valid for me. I
prefer to use GitHub Actions and GitHub webhooks to send emails to a
possible add-ons mailing list for commits, who was broken in Bitbucket
but that Mesar managed long time ago, was used at least by Abdel and
me, but I'm not sure if it could be replaced by a simpler solution
with GitHub Actions. I'm waiting for NV Access and stopped working on
add-ons until the system works well again, so I haven't investigated
this.
- Guidelines is a document originally created by Mesar, and I think it
should be reviewed including linting features and modifying the part
relative to appropiate add-on names. For instance, it's recommended
that add-on names don't include the word add-on, since it is redundant
in most cases, but for example it is perfectly appropiate for add-on
updater by Joseph.
- Add-on workflow is a document created by Mesar as a proposal, though
it's not applied.

About add-ons following guidelines, I think it's good to read them,
but it's difficult to follow models for this. They talk about code
style, release frequency, consult other add-ons and NVDA commands to
minimize conflicts, etc.

Cheers


2020-06-23 23:56 GMT+02:00, Luke Davis <luke@...>:
On Tue, 23 Jun 2020, Jim Homme wrote:

Two questions. First, is the guidance at
https://github.com/nvdaaddons/nvdaaddons.github.io/wiki still relevant?
I think Nolea may have to address that, although i believe that much of
it
is.

However, you should (also) be looking at these:

NVDA Developer Guide:
https://www.nvaccess.org/files/nvda/documentation/developerGuide.html
NVDA Add-on Development Guide:
https://github.com/nvdaaddons/devguide/wiki/NVDA%20Add-on%20Development%20Guide

Second, what is an add-on I can model my
first one after that follows the community-accepted guidelines?
That depends on what your add-on is trying to do.
Add-ons are written very differently depending on what they are supposed
to

accomplish.

Some have multiple python files, some have only one.
Some use config screens, some don't.
Some are global plugins, others are app modules.

What do you want your first add-on to be and do, in general?

For an example of the only one of mine I have made publicly available to
date,
look at https://github.com/XLTechie/debugHelper

You will see examples of an NVDA settings config window, use of the log,
use
of
global variables, and probably a few other concepts.
The python portion is only 142 lines.

For better, and bigger/more diverse, examples, Joseph Lee's add-ons are
usually
a very good source.
https://github.com/josephsl

Regards,

Luke






 

Hi,
In general, I tend to follow practices and norms from NVDA development -
variable names and case, source code comments and such. Whenever I do add-on
reviews, I look at the source code to make sure the copyright header is
present, trying to match what the source code says versus what the author
claims and such - I don't go into deeper reviews unless requested.
As for coding the add-on and style to be used and such, it depends on what
the ultimate goal of an add-on is: private use, limited distribution (say,
distributing on a company-wide network), public distribution (after going
through review), destined for inclusion in NVDA and what not. Even then,
folks are expected to follow at least some basics, namely camel case,
copyright statement, and source code text that makes sense - after all,
Python programming is a form of writing.
As for what I personally recommend, it is really up to add-on authors to
have willingness to follow basics and tailor their add-ons to the end result
in mind. Specifically:
* Private use: I leave it up to the author about code format and such.
* Public and limited distributions: authors must be willing to listen to
what users want and need, particularly more so if an add-on is to be used in
a limited distribution scenario such as deployment inside an enterprise or
school. Public distribution means authors should have committed to take
feedback from anyone and respond accordingly.
* Destined for NVDA: authors must follow coding style and guidelines from NV
access in addition to responding to feedback from the public. This is
trivial for anyone who have been watching NVDA source code changes
(including submitting pull requests), not so for new authors. The trick is
helping authors learn and adapt to higher standards and expectations, namely
coding style, extensive testing and feedback, compatibility with latest NVDA
code changes, organizing code so it can be transformed into a ready to
review pull request and such. Because of this, unless the author is a genius
or really set on doing it, I tend to advise new add-on authors away from
this option until they have demonstrated their willingness to make the leap
(listening and thinking about diverse feedback and code alignment is a
must).

For those who might ask: how do we prepare our add-ons for inclusion in
NVDA? Let me illustrate with a couple of examples:
* Search suggestion sounds: when I included this in Windows 10 App
Essentials add-on in 2017, I started out by defining an event handler for
UIA controller for event, letting NVDA detect and play suggestion sounds.
Then I moved onto defining controller for event inside a custom UIA search
field object, knowing that this object (or a slightly modified version) will
need to be added to NVDA itself. All these were tested extensively, knowing
that testing and user-level verification was a must before asking NV Access
to review a pull request I was working on (in short, the pull request I
wrote throughout 2017 was based on what I did with WinTenApps add-on with
slight modifications). Eventually search suggestions sound became part of
NVDA in 2017.
* Add-on Updater: shortly after NVDA gained ability to install and manage
add-ons (2012.2 in May 2012), there has been a request to let NVDA update
add-ons. Originally this work started out as a pull request, but it was
sidetracked many times, more so while porting NVDA to Python 3 in 2018. As
all of you know, this "pull request" eventually became Add-on Updater (I
still chuckle when people report that they used Add-on Updater to update
Add-on Updater). But people who have been looking at Add-on Updater source
code may have noticed that source files are named and organized similarly to
NVDA itself (addonHelperEx.py, for instance). This is intentional and
somewhat mirrors the actual pull request code associated with add-on
updating facility (NVDA issue 3208).

If you do decide to target your add-on for inclusion in NVDA (something we
should discuss more extensively in a separate thread), you must understand
that you need to think like an actual NVDA Core developer. This involves:
1. Thinking a lot. You are not only dealing with your own add-on code and
attitudes anymore - you must think about the impact of your change with
respect to rest of NVDA's own source code.
2. You must plan ahead. Because not all NVDA users use your add-on, you need
to think about potential advantages and drawbacks of your decisions.
3. You must have willingness to scrutinize your choices, especially design
decisions. Not only you need to think about impact of your choices with your
add-on (or a future iteration of it), you must scrutinize design decisions
as your code will now interact with a larger body of source code, including
being maintained by someone else.
4. Listening to diverse perspectives. An NVDA pull request based on your
add-on code will be read and commented by many people, potentially being
reviewed by folks whose cultural values are different than yours. Listening
to diverse feedback is a crucial skill you need to demonstrate as an add-on
author, more so if you want to send your add-on as an NVDA pull request.
5. As noted above, adapting your add-on code to match (or closely follow)
NVDA Core's coding style. This is more important as the first check a pull
request will go through is linting. To avoid build issues from Appveyor, I
strongly encourage would-be pull request writers to lint their code locally
first before committing changes.
6. Thinking about more and bigger errors. Transforming your add-on into a
pull request means you are exposing your changes to more possibilities,
including more errors and bigger bugs. You must have willingness to
understand, diagnose, debug, and communicate issues. When in doubt, pause
your work and ask yourself, "if I am a new NVDA user, what are possible
things I might be tempted to do?"

As I said, let's discuss the whole process of transforming an add-on into a
pull request in a separate thread.

Hope this helps.
Cheers,
Joseph

-----Original Message-----
From: nvda-addons@nvda-addons.groups.io <nvda-addons@nvda-addons.groups.io>
On Behalf Of Luke Davis
Sent: Tuesday, June 23, 2020 11:43 PM
To: nvda-addons@nvda-addons.groups.io
Subject: Re: [nvda-addons] Guidance For New Add-on Creator

Well, in general though, personally I would agree that the word "addon" or
"add-on" probably shouldn't be in the name either.

But there are some cases where there is a good reason to do this, such as
"Add-on Updater". "Updater" could refer to anything, but "Add-on Updater"
makes it clear what it updates.

The same is true for "NVDA Killer": it could kill anything, and needs the
clarity, but usually this would be redundant.

So it's just a matter of following common sense.

Like Noelia wrote in her other message:

"but it's difficult to follow models for this. They talk about code style,
release frequency, consult other add-ons and NVDA commands to minimize
conflicts, etc.
"

Which is exactly right. There are two many ways to do things. There may be
accepted ways of performing certain tasks in an add-on, and work that has
already been done that you can copy. But it's very hard to say "do it
exactly this way", without writing the add-on for someone. So all that can
be given are best practices most of the time.

And if you submit your add-on for review, the reviewers will probably tell
you if you've done something crazy.

Luke

Noelia wrote:

Sorry, about add-on names, the word add-on is not mentioned, just this:

2. Addon name should not contain "nvda", "plugin", "appmodule",
"globalPlugin" as part of its name, the user should not have to worry
about implementational issues.

Just to clarify :)
Anyway there are add-ons like Kill NVDA, which may need some of these
words.




2020-06-24 6:08 GMT+02:00, Noelia Ruiz via groups.io
<nrm1977=gmail.com@groups.io>:
Hi, I agree with Luke.
For the question about wiki, it contains articles valid for
reference, though some of them are not applicable now, until NV
Access can work fixing and, if needed, translating the system:
https://github.com/nvdaaddons/nvdaaddons.github.io/wiki/MakeAddonsTra
nslatable

Repos document hasn't been widely adopted: not many authors have
requested to add their repos to this document for reference, and it
hasn't been set as a requirement or suggestion most times, so it
isn't used in all its potential:

https://github.com/nvdaaddons/nvdaaddons.github.io/wiki/repos

Appveyor, GitHub Actions and GitHub webhooks are still valid for me.
I prefer to use GitHub Actions and GitHub webhooks to send emails to
a possible add-ons mailing list for commits, who was broken in
Bitbucket but that Mesar managed long time ago, was used at least by
Abdel and me, but I'm not sure if it could be replaced by a simpler
solution with GitHub Actions. I'm waiting for NV Access and stopped
working on add-ons until the system works well again, so I haven't
investigated this.
- Guidelines is a document originally created by Mesar, and I think
it should be reviewed including linting features and modifying the
part relative to appropiate add-on names. For instance, it's
recommended that add-on names don't include the word add-on, since it
is redundant in most cases, but for example it is perfectly
appropiate for add-on updater by Joseph.
- Add-on workflow is a document created by Mesar as a proposal,
though it's not applied.

About add-ons following guidelines, I think it's good to read them,
but it's difficult to follow models for this. They talk about code
style, release frequency, consult other add-ons and NVDA commands to
minimize conflicts, etc.

Cheers


2020-06-23 23:56 GMT+02:00, Luke Davis <luke@...>:
On Tue, 23 Jun 2020, Jim Homme wrote:

Two questions. First, is the guidance at
https://github.com/nvdaaddons/nvdaaddons.github.io/wiki still relevant?
I think Nolea may have to address that, although i believe that much
of it is.

However, you should (also) be looking at these:

NVDA Developer Guide:
https://www.nvaccess.org/files/nvda/documentation/developerGuide.htm
l
NVDA Add-on Development Guide:
https://github.com/nvdaaddons/devguide/wiki/NVDA%20Add-on%20Developm
ent%20Guide

Second, what is an add-on I can model my first one after that
follows the community-accepted guidelines?
That depends on what your add-on is trying to do.
Add-ons are written very differently depending on what they are
supposed to

accomplish.

Some have multiple python files, some have only one.
Some use config screens, some don't.
Some are global plugins, others are app modules.

What do you want your first add-on to be and do, in general?

For an example of the only one of mine I have made publicly
available to date, look at https://github.com/XLTechie/debugHelper

You will see examples of an NVDA settings config window, use of the
log, use of global variables, and probably a few other concepts.
The python portion is only 142 lines.

For better, and bigger/more diverse, examples, Joseph Lee's add-ons
are usually a very good source.
https://github.com/josephsl

Regards,

Luke







Noelia Ruiz
 

Hi, just to point out that I tend to recommend to follow style code,
thinking about impact, etc., from start. I try to do it though
obviously I'm not a genius. I think this is just something essential
unless we are learning, to facilitate work to reviewers and since when
we write add-ons regarding to the question of this thread they are for
the community.
I think that in some cases add-ons can be transformed in pull
requests, but sometimes it's easier to implement a feature in a pull
request instead of using an add-on, for instance in global commands.
So I tend to recommend authors to follow community guidelines and even
automatic processes, linting, thinking about configuration profiles
and diversity of users, for example making messages translatable,
using comments for translators, not just using tones but also
braillified messages, etc., from start. Just to bring my point of
view, in this case different to Joseph.
When I started writing add-ons, before this community was created, I
didn't use GitHub, nor guidelines etc., but now when I work in a
project I would try to use high standards from start and this is my
recommendation, trying to borrow further work not needed trying to do
things as better as possible from start. Obviously this is not the
case if I want to learn or test in the Python console
Cheers

2020-06-24 9:33 GMT+02:00, Joseph Lee <@joslee>:

Hi,
In general, I tend to follow practices and norms from NVDA development -
variable names and case, source code comments and such. Whenever I do
add-on
reviews, I look at the source code to make sure the copyright header is
present, trying to match what the source code says versus what the author
claims and such - I don't go into deeper reviews unless requested.
As for coding the add-on and style to be used and such, it depends on what
the ultimate goal of an add-on is: private use, limited distribution (say,
distributing on a company-wide network), public distribution (after going
through review), destined for inclusion in NVDA and what not. Even then,
folks are expected to follow at least some basics, namely camel case,
copyright statement, and source code text that makes sense - after all,
Python programming is a form of writing.
As for what I personally recommend, it is really up to add-on authors to
have willingness to follow basics and tailor their add-ons to the end
result
in mind. Specifically:
* Private use: I leave it up to the author about code format and such.
* Public and limited distributions: authors must be willing to listen to
what users want and need, particularly more so if an add-on is to be used
in
a limited distribution scenario such as deployment inside an enterprise or
school. Public distribution means authors should have committed to take
feedback from anyone and respond accordingly.
* Destined for NVDA: authors must follow coding style and guidelines from
NV
access in addition to responding to feedback from the public. This is
trivial for anyone who have been watching NVDA source code changes
(including submitting pull requests), not so for new authors. The trick is
helping authors learn and adapt to higher standards and expectations,
namely
coding style, extensive testing and feedback, compatibility with latest
NVDA
code changes, organizing code so it can be transformed into a ready to
review pull request and such. Because of this, unless the author is a
genius
or really set on doing it, I tend to advise new add-on authors away from
this option until they have demonstrated their willingness to make the leap
(listening and thinking about diverse feedback and code alignment is a
must).

For those who might ask: how do we prepare our add-ons for inclusion in
NVDA? Let me illustrate with a couple of examples:
* Search suggestion sounds: when I included this in Windows 10 App
Essentials add-on in 2017, I started out by defining an event handler for
UIA controller for event, letting NVDA detect and play suggestion sounds.
Then I moved onto defining controller for event inside a custom UIA search
field object, knowing that this object (or a slightly modified version)
will
need to be added to NVDA itself. All these were tested extensively, knowing
that testing and user-level verification was a must before asking NV Access
to review a pull request I was working on (in short, the pull request I
wrote throughout 2017 was based on what I did with WinTenApps add-on with
slight modifications). Eventually search suggestions sound became part of
NVDA in 2017.
* Add-on Updater: shortly after NVDA gained ability to install and manage
add-ons (2012.2 in May 2012), there has been a request to let NVDA update
add-ons. Originally this work started out as a pull request, but it was
sidetracked many times, more so while porting NVDA to Python 3 in 2018. As
all of you know, this "pull request" eventually became Add-on Updater (I
still chuckle when people report that they used Add-on Updater to update
Add-on Updater). But people who have been looking at Add-on Updater source
code may have noticed that source files are named and organized similarly
to
NVDA itself (addonHelperEx.py, for instance). This is intentional and
somewhat mirrors the actual pull request code associated with add-on
updating facility (NVDA issue 3208).

If you do decide to target your add-on for inclusion in NVDA (something we
should discuss more extensively in a separate thread), you must understand
that you need to think like an actual NVDA Core developer. This involves:
1. Thinking a lot. You are not only dealing with your own add-on code and
attitudes anymore - you must think about the impact of your change with
respect to rest of NVDA's own source code.
2. You must plan ahead. Because not all NVDA users use your add-on, you
need
to think about potential advantages and drawbacks of your decisions.
3. You must have willingness to scrutinize your choices, especially design
decisions. Not only you need to think about impact of your choices with
your
add-on (or a future iteration of it), you must scrutinize design decisions
as your code will now interact with a larger body of source code, including
being maintained by someone else.
4. Listening to diverse perspectives. An NVDA pull request based on your
add-on code will be read and commented by many people, potentially being
reviewed by folks whose cultural values are different than yours. Listening
to diverse feedback is a crucial skill you need to demonstrate as an add-on
author, more so if you want to send your add-on as an NVDA pull request.
5. As noted above, adapting your add-on code to match (or closely follow)
NVDA Core's coding style. This is more important as the first check a pull
request will go through is linting. To avoid build issues from Appveyor, I
strongly encourage would-be pull request writers to lint their code locally
first before committing changes.
6. Thinking about more and bigger errors. Transforming your add-on into a
pull request means you are exposing your changes to more possibilities,
including more errors and bigger bugs. You must have willingness to
understand, diagnose, debug, and communicate issues. When in doubt, pause
your work and ask yourself, "if I am a new NVDA user, what are possible
things I might be tempted to do?"

As I said, let's discuss the whole process of transforming an add-on into a
pull request in a separate thread.

Hope this helps.
Cheers,
Joseph


-----Original Message-----
From: nvda-addons@nvda-addons.groups.io <nvda-addons@nvda-addons.groups.io>
On Behalf Of Luke Davis
Sent: Tuesday, June 23, 2020 11:43 PM
To: nvda-addons@nvda-addons.groups.io
Subject: Re: [nvda-addons] Guidance For New Add-on Creator

Well, in general though, personally I would agree that the word "addon" or
"add-on" probably shouldn't be in the name either.

But there are some cases where there is a good reason to do this, such as
"Add-on Updater". "Updater" could refer to anything, but "Add-on Updater"
makes it clear what it updates.

The same is true for "NVDA Killer": it could kill anything, and needs the
clarity, but usually this would be redundant.

So it's just a matter of following common sense.

Like Noelia wrote in her other message:

"but it's difficult to follow models for this. They talk about code style,
release frequency, consult other add-ons and NVDA commands to minimize
conflicts, etc.
"

Which is exactly right. There are two many ways to do things. There may be
accepted ways of performing certain tasks in an add-on, and work that has
already been done that you can copy. But it's very hard to say "do it
exactly this way", without writing the add-on for someone. So all that can
be given are best practices most of the time.

And if you submit your add-on for review, the reviewers will probably tell
you if you've done something crazy.

Luke

Noelia wrote:

Sorry, about add-on names, the word add-on is not mentioned, just this:

2. Addon name should not contain "nvda", "plugin", "appmodule",
"globalPlugin" as part of its name, the user should not have to worry
about implementational issues.

Just to clarify :)
Anyway there are add-ons like Kill NVDA, which may need some of these
words.




2020-06-24 6:08 GMT+02:00, Noelia Ruiz via groups.io
<nrm1977=gmail.com@groups.io>:
Hi, I agree with Luke.
For the question about wiki, it contains articles valid for
reference, though some of them are not applicable now, until NV
Access can work fixing and, if needed, translating the system:
https://github.com/nvdaaddons/nvdaaddons.github.io/wiki/MakeAddonsTra
nslatable

Repos document hasn't been widely adopted: not many authors have
requested to add their repos to this document for reference, and it
hasn't been set as a requirement or suggestion most times, so it
isn't used in all its potential:

https://github.com/nvdaaddons/nvdaaddons.github.io/wiki/repos

Appveyor, GitHub Actions and GitHub webhooks are still valid for me.
I prefer to use GitHub Actions and GitHub webhooks to send emails to
a possible add-ons mailing list for commits, who was broken in
Bitbucket but that Mesar managed long time ago, was used at least by
Abdel and me, but I'm not sure if it could be replaced by a simpler
solution with GitHub Actions. I'm waiting for NV Access and stopped
working on add-ons until the system works well again, so I haven't
investigated this.
- Guidelines is a document originally created by Mesar, and I think
it should be reviewed including linting features and modifying the
part relative to appropiate add-on names. For instance, it's
recommended that add-on names don't include the word add-on, since it
is redundant in most cases, but for example it is perfectly
appropiate for add-on updater by Joseph.
- Add-on workflow is a document created by Mesar as a proposal,
though it's not applied.

About add-ons following guidelines, I think it's good to read them,
but it's difficult to follow models for this. They talk about code
style, release frequency, consult other add-ons and NVDA commands to
minimize conflicts, etc.

Cheers


2020-06-23 23:56 GMT+02:00, Luke Davis <luke@...>:
On Tue, 23 Jun 2020, Jim Homme wrote:

Two questions. First, is the guidance at
https://github.com/nvdaaddons/nvdaaddons.github.io/wiki still
relevant?
I think Nolea may have to address that, although i believe that much
of it is.

However, you should (also) be looking at these:

NVDA Developer Guide:
https://www.nvaccess.org/files/nvda/documentation/developerGuide.htm
l
NVDA Add-on Development Guide:
https://github.com/nvdaaddons/devguide/wiki/NVDA%20Add-on%20Developm
ent%20Guide

Second, what is an add-on I can model my first one after that
follows the community-accepted guidelines?
That depends on what your add-on is trying to do.
Add-ons are written very differently depending on what they are
supposed to

accomplish.

Some have multiple python files, some have only one.
Some use config screens, some don't.
Some are global plugins, others are app modules.

What do you want your first add-on to be and do, in general?

For an example of the only one of mine I have made publicly
available to date, look at https://github.com/XLTechie/debugHelper

You will see examples of an NVDA settings config window, use of the
log, use of global variables, and probably a few other concepts.
The python portion is only 142 lines.

For better, and bigger/more diverse, examples, Joseph Lee's add-ons
are usually a very good source.
https://github.com/josephsl

Regards,

Luke