Add 'Deprecation Policy' docs for 1.0.0.
Review Request #3457 - Created Feb. 12, 2016 and submitted
|benjyw, molsen, stuhood, zundel|
- Forklift the deprecation policy out of https://docs.google.com/document/d/1HDIalsQRv2Ds_uylPznX_VPmMdJib-1PdaGNVvF7fu4/edit#heading=h.g1bbfb2x9780 and into the official docs.
- This is not meant to be set in stone, but just to get something on the doc site as official fodder for citing in review discussions and such - please feel free to iterate on it as needed leading up to 1.0.0.
- Closes #2835.
./build-support/bin/publish_docs.sh -oand reviewed the new links and page.
CI (for good measure) is green at: https://travis-ci.org/pantsbuild/pants/builds/108705706
"Modules and methods" doesn't quite capture all cases.
It doesn't mention classes, for one thing. And we may also have functions and variables at the module level.
In fact, the most general definition requires recursion: what about a public method in a non-public class defined inside a public class defined inside a public module? :)
Maybe start with a definition:
A module, variable, function or class is part of the public API if its definition's docstring is marked
:API: publicin its docstring, and if its enclosing definition, if any, is part of the public API.
For example, a method
Bardefined at the top level of module
foois part of the public API iff the docstrings of
bazare all marked
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.
I'm not sure we need to enumerate "Excluding" - it's implied by the definition of "public API", so it's redundant?