API stability#
From 1.0.0, PolyPhys follows Semantic Versioning 2.0.0. This page says which names that promise covers and how a name is deprecated and removed.
What is public#
A name is public when it is listed in the __all__ of a module on the
API page. The methods and attributes of a public class that its
API page documents, those without a leading underscore, are public with the
class. Some packages, such as polyphys.probe and polyphys.simulate,
re-export public names of their modules; a re-export is the same object and
has the same status, and the module on the API page is its canonical
location. Every other name is private, even if it has no leading
underscore: a private name may change or disappear in any release, without a
deprecation period.
Each public module is stable or provisional:
Stable: a backward-incompatible change to a stable name comes only in a major release.
Provisional: the name may still change in a minor release. Each such change gets a
**Breaking:**entry in the changelog.
Module |
Status |
|---|---|
|
Stable |
|
Stable |
|
Stable |
|
Stable |
|
Provisional |
|
Provisional |
How a name is deprecated#
A stable public name that is to change or go away is first deprecated, in a minor release. Semantic Versioning requires the minor version to increase when public functionality is marked deprecated (clause 7), and its FAQ asks for at least one minor release that contains the deprecation before the functionality is removed in a major release [1]. So a deprecated name:
keeps working as before;
warns with
DeprecationWarningwhen it is used, naming its replacement and the release that removes it;carries a
.. deprecated::directive in its docstring, with the version that deprecated it; andgets a changelog entry under “Changed” that starts with
**Deprecated:**, since Common Changelog has no “Deprecated” category and lists a deprecation under “Changed”.
A deprecated name is removed only in the next major release, after at least
one minor release has shipped its warning. The removal gets a
**Breaking:** changelog entry with the migration path.
Before 1.0.0#
While the major version was 0, anything could change in any release
(Semantic Versioning, clause 4). The breaking changes since 0.4.0, and how
to migrate from each, are listed in CHANGELOG.md, under “Migrating to
1.0.0”.