Skip to content

Commit 553f502

Browse files
committed
update deprecation policy
1 parent 79f9265 commit 553f502

File tree

1 file changed

+37
-10
lines changed

1 file changed

+37
-10
lines changed

CONTRIBUTING.md

Lines changed: 37 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -361,22 +361,49 @@ There are a few other build options available:
361361

362362
### Deprecation policy
363363

364-
Qiskit Experiments's deprecation policy is based on Qiskit's [Deprecation
365-
Policy](https://github.com/Qiskit/qiskit/blob/45e42525224e9e1857300e7e5529273fe619c9e4/DEPRECATION.md)
366-
prior to its 1.0 release. Public-facing changes must come with a deprecation warning
367-
for at least three months or two version cycles before the old feature is removed.
368-
Deprecations can only happen on minor releases and not on patch releases.
364+
Any change to the existing package code that affects how the user interacts with the package
365+
should give the user clear instructions and advanced warning if the change is nontrivial.
366+
Qiskit Experiments's deprecation policy is based on [Qiskit's
367+
policy](https://github.com/Qiskit/qiskit/blob/1.0.0rc1/DEPRECATION.md) prior to its 1.0 release, but
368+
we impose less stringent requirements such that developers can iterate more quickly.
369+
Deprecations and feature removals can only happen on minor releases and not on patch releases.
370+
371+
The deprecation policy depends on the significance of the user-facing change, which we have divided into
372+
three categories:
373+
374+
A **core feature change** is one that affects how the framework functions, for example a
375+
change to `BaseExperiment`. The timeline for deprecating an existing core feature is as follows:
376+
377+
* Minor release 1: An alternative path is provided. A `PendingDeprecationWarning`
378+
should be issued when the old path is used, indicating to users how to switch to
379+
the new path and the release in which the old path will no longer be available. The
380+
developer may choose to directly deprecate the feature and issue a `DeprecationWarning` instead,
381+
in which case the release note should indicate the feature has been deprecated and how to switch
382+
to the new path.
383+
* Minor release 2: The `PendingDeprecationWarning` becomes a `DeprecationWarning`, or the
384+
`DeprecationWarning` remains in place. The release note should indicate the feature has
385+
been deprecated and how to switch to the new path.
386+
* Minor release 3: The old feature is removed. The release note should indicate that the feature has
387+
been removed and how to switch to the new path.
388+
389+
If the three-release cycle takes fewer than three months, the feature removal must wait for more
390+
releases until three months has elapsed since the first issuing of the `PendingDeprecationWarning`
391+
or `DeprecationWarning`.
369392

370-
The timeline for deprecating an existing feature is as follows:
393+
A **non-core feature change** may be a change to a specific experiment class or modules such as the
394+
plotter. The timeline is shortened for such a change:
371395

372-
* Minor release 1: An alternative path is provided. A `PendingDeprecationWarning` should be issued
396+
* Minor release 1: An alternative path is provided. A `DeprecationWarning` should be issued
373397
when the old path is used, indicating to users how to switch to the new path and the release
374398
in which the old path will no longer be available.
375-
* Minor release 2: The `PendingDeprecationWarning` becomes a `DeprecationWarning`. The release note
376-
should indicate the feature has been deprecated and how to switch to the new path.
377-
* Minor release 3: The old feature is removed. The release note should indicate that the feature has
399+
* Minor release 2: The old feature is removed. The release note should indicate that the feature has
378400
been removed and how to switch to the new path.
379401

402+
Lastly, a **minor, non-core change** would include cosmetic changes such as output file names and
403+
changes to helper functions that isn't directly used in the package code base. These can be made in
404+
one release without a deprecation process as long as the change is clearly described in the
405+
release notes.
406+
380407
#### Adding deprecation warnings
381408

382409
We use the deprecation wrappers in [Qiskit

0 commit comments

Comments
 (0)