1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
|
# Torchvision maintainers guide
This document aims at documenting user-facing policies / principles used when
developing and maintaining torchvision. Other maintainer info (e.g. release
process) can be found in the meta-internal wiki.
### What is public and what is private?
For the Python API, torchvision largely follows the [PyTorch
policy](https://github.com/pytorch/pytorch/wiki/Public-API-definition-and-documentation)
which is consistent with other major packages
([numpy](https://numpy.org/neps/nep-0023-backwards-compatibility.html),
[scikit-learn](https://scikit-learn.org/dev/glossary.html#term-API) etc.).
We recognize that his policy is somewhat imperfect for some edge cases, and that
it's difficult to come up with an accurate technical definition. In broad terms,
which are usually well understood by users, the policy is that:
- modules that can be accessed without leading underscore are public
- objects in a public file that don't have a leading underscore are public
- class attributes are public iff they have no leading underscore
- the rest of the modules / objects / class attributes are considered private
The public API has backward-compatible (BC) guarantees defined in our
deprecation policy (see below). The private API has not BC guarantees.
For C++, code is private. For Meta employees: if a C++ change breaks fbcode, fix
fbcode or revert the change. We should be careful about models running in
production and relying on torchvision ops.
The `test` folder is not importable and is **private.** Even meta-internal
projects should *not* rely on it (it has happened in the past and is now
programmatically impossible).
The training references do not have BC guarantees. Breaking changes are
possible, but we should make sure that the tutorials are still running properly,
and that their intended narrative is preserved (by e.g. checking outputs,
etc.).
The rest of the folders (build, android, ios, etc.) are private and have no BC
guarantees.
### Deprecation policy.
Because they're disruptive, **deprecations should only be used sparingly**.
We largely follow the [PyTorch
policy](https://github.com/pytorch/pytorch/wiki/PyTorch's-Python-Frontend-Backward-and-Forward-Compatibility-Policy):
breaking changes require a deprecation period of at least 2 versions.
Deprecations should clearly indicate their deadline in the docs and warning
messages. Avoid not committing to a deadline, or keeping deprecated APIs for too
long: it gives no incentive for users to update their code, sends conflicting
messages ("why was this API removed while this other one is still around?"), and
accumulates debt in the project.
### Should this attribute be public? Should this function be private?
When designing an API it’s not always obvious what should be exposed as public,
and what should be kept as a private implementation detail. The following
guidelines can be useful:
* Functional consistency throughout the library is a top priority, for users and
developers’ sake. In doubt and unless it’s clearly wrong, expose what other
similar classes expose.
* Think really hard about the users and their use-cases, and try to expose what
they would need to address those use-cases. Aggressively keep everything else
private. Remember that the “private -> public” direction is way smoother than
the “public -> private” one: in doubt, keep it private.
* When thinking about use-cases, the general API motto applies: make what’s
simple and common easy, and make what’s complex possible (80% / 20% rule).
There might be a ~1% left that’s not addressed: that’s OK. Also, **make what’s
wrong very hard**, if not impossible.
As a good practice, always create new files and even classes with a leading
underscore in their name. This way, everything is private by default and the
only public surface is explicitly present in an `__init__.py` file.
|
