Skip to content

Commit e704e08

Browse files
seanbuddseanbudd
authored
Merge a1be276 into 1751403 
2 parents 1751403 + a1be276 commit e704e08

3 files changed

Lines changed: 52 additions & 8 deletions

File tree

‎devDocs/deprecations.md‎

Lines changed: 34 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,43 @@
1+
2+
# Deprecations
3+
4+
## Background
15
The NVDA API must maintain compatibility with add-ons throughout yearly development cycles.
26
The first release of a year, i.e. `20XX.1`, is when the NVDA API can introduce breaking changes.
37

4-
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.
8+
## Deprecations
9+
Where possible, ensure the NVDA API maintains backwards compatibility.
10+
If no removal is required or proposed, backwards compatibility can be maintained via the following snippet:
11+
12+
```py
13+
import globalVars
14+
def __getattr__(attrName: str) -> Any:
15+
"""Module level `__getattr__` used to preserve backward compatibility."""
16+
if attrName == "deprecatedSymbolName" and globalVars._allowDeprecatedAPI:
17+
# Note: this should only log in situations where it will not be excessively noisy.
18+
log.warning(
19+
"Importing deprecatedSymbolName from here is deprecated. "
20+
"Import X instead and do Y. "
21+
)
22+
# Ensure the API of deprecatedSymbolNameReplacement is the same as the deprecated symbol.
23+
return deprecatedSymbolNameReplacement
24+
raise AttributeError(f"module {repr(__name__)} has no attribute {repr(attrName)}")
25+
```
26+
27+
28+
## Required API breaking changes
29+
In order to improve the NVDA API, changes that will break future compatibility may be implemented, as long they retain backwards compatibility until the `20XX.1` release.
530

631
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.
732
```python
833
from buildVersion import version_year
9-
if version_year < NEXT_YEAR:
34+
import globalVars
35+
if version_year < NEXT_YEAR and globalVars._allowDeprecatedAPI:
1036
foo = bar
1137
```
1238

39+
## Testing backwards compatibility
40+
1341
To ensure a module retains the same symbol names being importable, check across versions what is imported using the NVDA python console.
1442
```python
1543
import controlTypes
@@ -19,3 +47,7 @@ dir(controlTypes)
1947
Changes different to moving or renaming symbols need to be considered carefully with a different approach.
2048

2149
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.
50+
51+
## Announcements
52+
Deprecations should be announced via the [NVDA API mailing list](https://groups.google.com/a/nvaccess.org/g/nvda-api/about).
53+

‎devDocs/developerGuide.t2t‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,22 @@ NVDA NVDA_VERSION Developer Guide
1212
+ Introduction +
1313
This guide provides information concerning NVDA development, including translation and the development of components for NVDA.
1414

15+
++ API stability ++
16+
The NVDA API only includes symbols which are not marked with prefixing underscores.
17+
18+
The NVDA Add-on API changes over time, such as removals, deprecations and new features.
19+
Important changes to the API are announced on the [NVDA API mailing list https://groups.google.com/a/nvaccess.org/g/nvda-api/about].
20+
21+
API breaking releases happen at most once per year, these are ``.1`` releases, e.g. ``2022.1``.
22+
The API remains backwards compatible between breaking releases.
23+
API breaking changes should be considered relatively stable in the first beta: e.g. ``2022.1.beta1``.
24+
25+
API features may become deprecated over time.
26+
Deprecated API features may have a scheduled removal date, a future breaking release (e.g. ``2022.1``).
27+
Deprecations may also have no scheduled removal date, and will remain supported until it is no longer reasonable.
28+
Note, the roadmap for removals is 'best effort' and may be subject to change.
29+
Please open a GitHub issue if these changes stop the API from meeting your needs.
30+
1531
++ A Note About Python ++
1632
NVDA and its components are primarily written in the Python programming language.
1733
It is not the goal of this guide to teach you Python, though examples are provided through out this guide which will help to familiarise you with the Python syntax.

‎user_docs/en/changes.t2t‎

Lines changed: 2 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -25,15 +25,11 @@ What's New in NVDA
2525

2626

2727
== Changes for Developers ==
28+
- The [NVDA API Announcement mailing list https://groups.google.com/a/nvaccess.org/g/nvda-api/about] was created. (#13999)
29+
-
2830

2931

3032
=== Deprecations ===
31-
These are proposed API breaking changes.
32-
The deprecated part of the API will continue to be available until the specified release.
33-
If no release is specified, the plan for removal has not been determined.
34-
Note, the roadmap for removals is 'best effort' and may be subject to change.
35-
Please test the new API and provide feedback.
36-
For add-on authors, please open a GitHub issue if these changes stop the API from meeting your needs.
3733

3834

3935
= 2022.3 =

0 commit comments

Comments
 (0)