Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Backwards compatible control types refactor #12510

Merged
merged 2 commits into from
Jun 30, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions devDocs/codingStandards.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,7 @@ for more information.
- E.G. `BrailleHandler`.
* Constants should be all upper case, separating words with underscores;
- E.G. `LANGS_WITH_CONJUNCT_CHARS`.
- Avoid unnecesary shared prefixes in constants. Instead, use an enum for related constants.
* Event handlers are prefixed with "event_", subsequent words in camel case.
Note, `object` and `action` are separated by underscores.
- E.G.: `event_action` or `event_object_action`.
Expand All @@ -59,6 +60,13 @@ for more information.
- TBD. Ideally follows a similar style the others, and communicates if the filtering happens
before or after some action.
- It would also be nice to have a naming scheme that differentiates it from the others.
* Enums should be formatted using the expected mix of above eg:
```python
class ExampleGroupOfData(Enum):
CONSTANT_VALUE_MEMBER = auto()
@property
def _formatMember(self): pass
```

seanbudd marked this conversation as resolved.
Show resolved Hide resolved
### Translatable Strings
* All strings that could be presented to the user should be marked as translatable using the `_()`
Expand Down Expand Up @@ -86,3 +94,11 @@ self.copySettingsButton = wx.Button(
)
)
```

### Imports
* Unused imports should be removed where possible.
- Anything imported into a (sub)module can also be imported from that submodule.
- As a result, removing unused imports may break compatibility, and should be done in compatibility breaking releases (see `deprecations.md`).
* Unused imports will give a lint warning. These can be handled the following ways:
- If these imports are inteded to be imported from other modules, they can be done included in a definition for `__all__`. This will override and define the symbols imported when performing a star import, eg `from module import *`.
- Otherwise, with a comment like `# noqa: <explanation>`.
21 changes: 21 additions & 0 deletions devDocs/deprecations.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
The NVDA API must maintain compatibility with add-ons throughout yearly development cycles.
The first release of a year, i.e. `20XX.1`, is when the NVDA API can introduce breaking changes.

In order to improve the NVDA API, changes that will break future compatibility can be implemented, as long they retain backwards compatibility until the `20XX.1` release.

This can be done by using a version check to automate deprecation. For example, if you wish to replace usages of `foo` with `bar`. When we begin work on `NEXT_YEAR`, `foo` will no longer be part of the NVDA API and all internal usages must be removed prior.
```python
from buildVersion import version_year
if version_year < NEXT_YEAR:
foo = bar
```

To ensure a module retains the same symbol names being importable, check across versions what is imported using the NVDA python console.
```python
import controlTypes
dir(controlTypes)
```

Changes different to moving or renaming symbols need to be considered carefully with a different approach.

Any API breaking changes such as deprecations marked for removal should be commented with the year of intended removal, and notes on how to implement the API change as an add-on developer and NVDA developer.
Loading