Pants Deprecation Policy
Deprecations should live for one entire
dev series and stable release branch (at the minimum) before their code is removed. This ensures that there is always at least one stable release containing a deprecation, and allows users upgrading their copy of pants to consume only stable releases in order to observe all deprecations.
As an example: if a feature is deprecated in
1.0.0.dev2, it should remain available but deprecated for the entire
1.1.0.dev series, and can be removed when master bumps to
A module, variable, method, function or class is part of the public API if:
- Its definition's docstring is marked
:API: public, and its enclosing definition, if any, is part of the public API.
- It's abstract or effectively abstract (required to be re-defined by the declaring class) and its declaring class or any inheriting class published by Pants is marked
For example, a method
baz of class
Bar defined at the top level of module
foo is part of the public API if and only if the docstrings of
baz are all marked
:API: public. e.g.
$ cat foo.py """ An example public API module. :API: public """ class Bar: """An example public API class. :API: public """ def baz(self): """An example public API method. :API: public """ def qux(self): """An example public API function. :API: public """
As a special exception, some legacy subsystem types are marked
:API: public and implicitly have all their registered options exposed as
:API: public members.
Going forward its expected new subsystem types are just factories for options-configured plain old types; so the type and its factory method will be the only
:API: public members of subsytems.
The following rules apply to definitions in the public API. No rules apply to definitions outside the public API. Those may be changed in any way at any time.
In the case of a legal requirement to change API's we will make our best effort to minimize impact for plugin developers.
Allowed API Changes
- Adding a new module.
- Adding new command line options.
- Adding new features to existing modules.
- Deprecate and warn about an API that has been refactored.
- Deprecate and warn about an option that has been refactored.
- Adding new named/defaulted parameters to a public API method.
- Adding/removing/renaming any module or method in a directory named 'exp'.
- Adding/removing/renaming any module or method not marked
:API: publicin the docstring.
- Fixing bugs.
- Exceptions for severe or special case bugs may be considered on a case-by-case basis.
- API changes that would normally be disallowed but are legally required.
Disallowed API Changes
- Deprecated options must continue to work as before.
- Existing API modules cannot be moved.
- Options cannot be removed.
- Parameters cannot be removed from API methods (any public method in an API module).
- Changing the behavior of a method that breaks existing assumptions.
- e.g. changing a method that used to do transitive resolution to intransitive resolution would be disallowed, but adding a new named parameter to change the behavior would be allowed.
- Changes that introduce significant performance regressions by default.
- A significant regression would be a slowdown of >= 10%.
- If a new feature is needed that would slow down performance more than 10%, it should be put behind an option.