Skip to content

Commit 9f433ed

Browse files
seanbuddseanbudd
authored
Merge 4508855 into 11cb7e7 
2 parents 11cb7e7 + 4508855 commit 9f433ed

3 files changed

Lines changed: 56 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: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,24 @@ 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 ++[API]
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+
Changes relevant to developers are also announced via the [NVDA changes file](https://www.nvaccess.org/files/nvda/documentation/changes.html).
21+
Any changes to the API policy outlined in this section will be conveyed via these two channels.
22+
23+
API breaking releases happen at most once per year, these are ``.1`` releases, e.g. ``2022.1``.
24+
The API remains backwards compatible between breaking releases.
25+
API breaking changes should be considered relatively stable in the first beta: e.g. ``2022.1.beta1``.
26+
27+
API features may become deprecated over time.
28+
Deprecated API features may have a scheduled removal date, a future breaking release (e.g. ``2022.1``).
29+
Deprecations may also have no scheduled removal date, and will remain supported until it is no longer reasonable.
30+
Note, the roadmap for removals is 'best effort' and may be subject to change.
31+
Please open a GitHub issue if these changes stop the API from meeting your needs.
32+
1533
++ A Note About Python ++
1634
NVDA and its components are primarily written in the Python programming language.
1735
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: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -40,15 +40,13 @@ What's New in NVDA
4040

4141

4242
== Changes for Developers ==
43+
Please refer to [the developer guide https://www.nvaccess.org/files/nvda/documentation/developerGuide.html#API] for information on NVDA's API deprecation and removal process.
44+
45+
- The [NVDA API Announcement mailing list https://groups.google.com/a/nvaccess.org/g/nvda-api/about] was created. (#13999)
46+
-
4347

4448

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

5351

5452
= 2022.3 =

0 commit comments

Comments
 (0)