@@ -361,22 +361,49 @@ There are a few other build options available:
361
361
362
362
### Deprecation policy
363
363
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 ` .
369
392
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:
371
395
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
373
397
when the old path is used, indicating to users how to switch to the new path and the release
374
398
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
378
400
been removed and how to switch to the new path.
379
401
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
+
380
407
#### Adding deprecation warnings
381
408
382
409
We use the deprecation wrappers in [ Qiskit
0 commit comments