{"payload":{"allShortcutsEnabled":false,"fileTree":{"":{"items":[{"name":".azure","path":".azure","contentType":"directory"},{"name":".binder","path":".binder","contentType":"directory"},{"name":".cargo","path":".cargo","contentType":"directory"},{"name":".github","path":".github","contentType":"directory"},{"name":"crates","path":"crates","contentType":"directory"},{"name":"docs","path":"docs","contentType":"directory"},{"name":"examples","path":"examples","contentType":"directory"},{"name":"qiskit","path":"qiskit","contentType":"directory"},{"name":"releasenotes","path":"releasenotes","contentType":"directory"},{"name":"test","path":"test","contentType":"directory"},{"name":"tools","path":"tools","contentType":"directory"},{"name":".editorconfig","path":".editorconfig","contentType":"file"},{"name":".git-blame-ignore-revs","path":".git-blame-ignore-revs","contentType":"file"},{"name":".gitignore","path":".gitignore","contentType":"file"},{"name":".local-spellings","path":".local-spellings","contentType":"file"},{"name":".mailmap","path":".mailmap","contentType":"file"},{"name":".mergify.yml","path":".mergify.yml","contentType":"file"},{"name":".stestr.conf","path":".stestr.conf","contentType":"file"},{"name":"CITATION.bib","path":"CITATION.bib","contentType":"file"},{"name":"CODE_OF_CONDUCT.md","path":"CODE_OF_CONDUCT.md","contentType":"file"},{"name":"CONTRIBUTING.md","path":"CONTRIBUTING.md","contentType":"file"},{"name":"Cargo.lock","path":"Cargo.lock","contentType":"file"},{"name":"Cargo.toml","path":"Cargo.toml","contentType":"file"},{"name":"DEPRECATION.md","path":"DEPRECATION.md","contentType":"file"},{"name":"LICENSE.txt","path":"LICENSE.txt","contentType":"file"},{"name":"MAINTAINING.md","path":"MAINTAINING.md","contentType":"file"},{"name":"MANIFEST.in","path":"MANIFEST.in","contentType":"file"},{"name":"Makefile","path":"Makefile","contentType":"file"},{"name":"README.md","path":"README.md","contentType":"file"},{"name":"SECURITY.md","path":"SECURITY.md","contentType":"file"},{"name":"asv.conf.json","path":"asv.conf.json","contentType":"file"},{"name":"azure-pipelines.yml","path":"azure-pipelines.yml","contentType":"file"},{"name":"constraints.txt","path":"constraints.txt","contentType":"file"},{"name":"pyproject.toml","path":"pyproject.toml","contentType":"file"},{"name":"qiskit_bot.yaml","path":"qiskit_bot.yaml","contentType":"file"},{"name":"requirements-dev.txt","path":"requirements-dev.txt","contentType":"file"},{"name":"requirements-optional.txt","path":"requirements-optional.txt","contentType":"file"},{"name":"requirements.txt","path":"requirements.txt","contentType":"file"},{"name":"rust-toolchain.toml","path":"rust-toolchain.toml","contentType":"file"},{"name":"setup.py","path":"setup.py","contentType":"file"},{"name":"tox.ini","path":"tox.ini","contentType":"file"}],"totalCount":41}},"fileTreeProcessingTime":9.456812,"foldersToFetch":[],"repo":{"id":83821669,"defaultBranch":"main","name":"qiskit","ownerLogin":"Qiskit","currentUserCanPush":false,"isFork":false,"isEmpty":false,"createdAt":"2017-03-03T17:02:42.000Z","ownerAvatar":"https://avatars.githubusercontent.com/u/30696987?v=4","public":true,"private":false,"isOrgOwned":true},"symbolsExpanded":false,"treeExpanded":true,"refInfo":{"name":"main","listCacheKey":"v0:1710785011.0","canEdit":false,"refType":"branch","currentOid":"43381ae1b159c01b55159d2dc1e8a65970b72746"},"path":"DEPRECATION.md","currentUser":null,"blob":{"rawLines":null,"stylingDirectives":null,"colorizedLines":null,"csv":null,"csvError":null,"dependabotInfo":{"showConfigurationBanner":false,"configFilePath":null,"networkDependabotPath":"/Qiskit/qiskit/network/updates","dismissConfigurationNoticePath":"/settings/dismiss-notice/dependabot_configuration_notice","configurationNoticeDismissed":null},"displayName":"DEPRECATION.md","displayUrl":"https://github.com/Qiskit/qiskit/blob/main/DEPRECATION.md?raw=true","headerInfo":{"blobSize":"12.8 KB","deleteTooltip":"You must be signed in to make or propose changes","editTooltip":"You must be signed in to make or propose changes","ghDesktopPath":"https://desktop.github.com","isGitLfs":false,"onBranch":true,"shortPath":"bc413bd","siteNavLoginPath":"/login?return_to=https%3A%2F%2Fgithub.com%2FQiskit%2Fqiskit%2Fblob%2Fmain%2FDEPRECATION.md","isCSV":false,"isRichtext":true,"toc":[{"level":1,"text":"Deprecation Policy","anchor":"deprecation-policy","htmlText":"Deprecation Policy"},{"level":2,"text":"Principles","anchor":"principles","htmlText":"Principles"},{"level":2,"text":"What is the public interface?","anchor":"what-is-the-public-interface","htmlText":"What is the public interface?"},{"level":2,"text":"Removing a feature","anchor":"removing-a-feature","htmlText":"Removing a feature"},{"level":2,"text":"Changing behavior","anchor":"changing-behavior","htmlText":"Changing behavior"},{"level":2,"text":"Issuing deprecation warnings","anchor":"issuing-deprecation-warnings","htmlText":"Issuing deprecation warnings"},{"level":2,"text":"Testing deprecated functionality","anchor":"testing-deprecated-functionality","htmlText":"Testing deprecated functionality"},{"level":2,"text":"Documenting deprecations and breaking changes","anchor":"documenting-deprecations-and-breaking-changes","htmlText":"Documenting deprecations and breaking changes"}],"lineInfo":{"truncatedLoc":"257","truncatedSloc":"183"},"mode":"file"},"image":false,"isCodeownersFile":null,"isPlain":false,"isValidLegacyIssueTemplate":false,"issueTemplate":null,"discussionTemplate":null,"language":"Markdown","languageID":222,"large":false,"planSupportInfo":{"repoIsFork":null,"repoOwnedByCurrentUser":null,"requestFullPath":"/Qiskit/qiskit/blob/main/DEPRECATION.md","showFreeOrgGatedFeatureMessage":null,"showPlanSupportBanner":null,"upgradeDataAttributes":null,"upgradePath":null},"publishBannersInfo":{"dismissActionNoticePath":"/settings/dismiss-notice/publish_action_from_dockerfile","releasePath":"/Qiskit/qiskit/releases/new?marketplace=true","showPublishActionBanner":false},"rawBlobUrl":"https://github.com/Qiskit/qiskit/raw/main/DEPRECATION.md","renderImageOrRaw":false,"richText":"

Deprecation Policy

\n

Starting from the 1.0.0 release, Qiskit follows semantic versioning, with a yearly release cycle for major releases.\nFull details of the scheduling are hosted with the external public documentation.

\n

This document is primarily intended for developers of Qiskit themselves.

\n

Principles

\n

Many users and other packages depend on different parts of Qiskit. We must\nmake sure that whenever we make changes to the code, we give users ample time to\nadjust without breaking code that they have already written.

\n

Most importantly: do not change any interface that is public-facing unless we\nabsolutely have to. Adding things is ok, taking things away is annoying for\nusers but can be handled reasonably with plenty notice, but changing behavior\ngenerally means users cannot write code that will work with two subsequent\nversions of Qiskit, which is not acceptable.

\n

Beware that users will often be using functions, classes and methods that we,\nthe Qiskit developers, may consider internal or not widely used. Do not make\nassumptions that \"this is buried, so nobody will be using it\"; if it is public,\nit is subject to the policy. The only exceptions here are functions and modules\nthat are explicitly internal, i.e. those whose names begin with a leading\nunderscore (_).

\n

The guiding principles are:

\n\n

While the no-breaking-changes rule is only formally required within a major release series, you should make every effort to avoid breaking changes wherever possible.\nSimilarly, while it is permissible where necessary for behavior to change with no single-code path to support both the last minor of one major release and the first minor of a new major release, it is still strongly preferable if you can achieve this.

\n

What is the public interface?

\n

Note

This section should be in sync with the release schedule documentation of Qiskit.\nPlease open an issue against Qiskit if there are discrepancies so we can clarify them.

\n
\n

For the purposes of semantic versioning, the Qiskit public API comprises all publicly documented packages, modules, classes, functions, methods, and attributes.

\n

An object is publicly documented if and only if it appears in the hosted API documentation for Qiskit.\nThe presence of a docstring in the Python source (or a __doc__ attribute) is not sufficient to make an object publicly documented; this documentation must also be rendered in the public API documentation.

\n

As well as the objects themselves needing to be publicly documented, the only public-API import locations for a given object is the location it is documented at in the public API documentation, and parent modules or packages that re-export the object (if any).\nFor example, while it is possible to import Measure from qiskit.circuit.measure, this is not a supported part of the public API for two reasons:

\n
    \n
  1. The module qiskit.circuit.measure is not publicly documented, so is not part of the public interface.
  2. \n
  3. The Measure object is documented as being in qiskit.circuit.library, and is re-exported by qiskit.circuit, so the public import paths are from qiskit.circuit.library import Measure and from qiskit.circuit import Measure.
  4. \n
\n

As a rule of thumb, if you are using Qiskit, you should import objects from the highest-level package that exports that object.

\n

Some components of the documented public interface may be marked as \"experimental\", and not subject to the stability guarantees of semantic versioning.\nThese will be clearly denoted in the documentation, and will raise an ExperimentalWarning when used.\nWe will only use these \"experimental\" features sparingly, when we feel there is a real benefit to making the experimental version public in an unstable form, such as a backwards-incompatible new version of core functionality that shows significant improvements over the existing form for limited inputs, but is not yet fully feature complete.\nTypically, a feature will only become part of the public API when we are ready to commit to its stability properly.

\n

Removing a feature

\n

Important

Features can only be removed in new major versions.\nDeprecations can only be added in new minor versions.

\n
\n

When removing a feature (for example a class, function or function parameter),\nwe will follow this procedure:

\n\n

Note

These are minimum requirements.\nFor removal of significant or core features, try to give as long a warning period as is feasible.

\n
\n

When a feature is marked as deprecated it is slated for removal, but users\nshould still be able to rely on it to work correctly. We consider a feature\nmarked \"deprecated\" as frozen; we commit to maintaining it with critical bug\nfixes until it is removed, but we won't merge new functionality to it.

\n

Changing behavior

\n

Important

Breaking behavior changes can only occur in new major versions, and should be avoided as much as possible.

\n
\n

Changing behavior without a removal is particularly difficult to manage, because\nwe need to have both options available for two versions, and be able to issue\nwarnings. For example, changing the type of the return value from a function\nwill almost invariably involve making an API break, which is frustrating for\nusers and makes it difficult for them to use Qiskit.

\n

The best solution here is often to make a new function, and then use the procedures for removal above.

\n

If you absolutely must change the behavior of existing code (other than fixing\nbugs), you will need to use your best judgment to apply the guiding principles\nat the top of this document. The most appropriate warning for behavioral\nchanges is usually FutureWarning. Some possibilities for how to effect a\nchange:

\n\n

Issuing deprecation warnings

\n

The proper way to raise a deprecation warning is to use the decorators @deprecate_arg and\n@deprecate_func from qiskit.utils.deprecation. These will generate a standardized message and\nand add the deprecation to that function's docstring so that it shows up in the docs.

\n
from qiskit.utils.deprecation import deprecate_arg, deprecate_func\n\n@deprecate_func(since=\"0.24.0\", additional_msg=\"No replacement is provided.\")\ndef deprecated_func():\n    pass\n\n@deprecate_arg(\"bad_arg\", new_alias=\"new_name\", since=\"0.24.0\")\ndef another_func(bad_arg: str, new_name: str):\n    pass
\n

Usually, you should set additional_msg: str with the format \"Instead, use ...\" so that\npeople know how to migrate. Read those functions' docstrings for additional arguments like\npending: bool and predicate.

\n

If you are deprecating outside the main Qiskit repo, set package_name to match your package.\nAlternatively, if you prefer to use your own decorator helpers, then have them call\nadd_deprecation_to_docstring from qiskit.utils.deprecation.

\n

If @deprecate_func and @deprecate_arg cannot handle your use case, consider improving\nthem. Otherwise, you can directly call the warn function\nfrom the warnings module in the Python standard library,\nusing the category DeprecationWarning. For example:

\n
import warnings\n\ndef deprecated_function():\n   warnings.warn(\n      \"The function qiskit.deprecated_function() is deprecated since \"\n      \"Qiskit 0.44.0, and will be removed 3 months or more later. \"\n      \"Instead, you should use qiskit.other_function().\",\n      category=DeprecationWarning,\n      stacklevel=2,\n   )\n   # ... the rest of the function ...
\n

Make sure you include the version of the package that introduced the deprecation\nwarning (so maintainers can easily see when it is valid to remove it), and what\nthe alternative path is.

\n

Take note of the stacklevel argument. This controls which function is\naccused of being deprecated. Setting stacklevel=1 (the default) means the\nwarning will blame the warn function itself, while stacklevel=2 will\ncorrectly blame the containing function. It is unusual to set this to anything\nother than 2, but can be useful if you use a helper function to issue the\nsame warning in multiple places.

\n

Testing deprecated functionality

\n

Whenever you add deprecation warnings, you will need to update tests involving\nthe functionality. The test suite should fail otherwise, because of the new\nwarnings. We must continue to test deprecated functionality throughout the\ndeprecation period, to ensure that it still works.

\n

To update the tests, you need to wrap each call of deprecated behavior in its\nown assertion block. For subclasses of unittest.TestCase (which all Qiskit\ntest cases are), this is done by:

\n
class MyTestSuite(QiskitTestCase):\n   def test_deprecated_function(self):\n      with self.assertWarns(DeprecationWarning):\n         output = deprecated_function()\n      # ... do some things with output ...\n      self.assertEqual(output, expected)
\n

Documenting deprecations and breaking changes

\n

It is important to warn the user when your breaking changes are coming.

\n

@deprecate_arg and @deprecate_func will automatically add the deprecation to the docstring\nfor the function so that it shows up in docs.

\n

If you are not using those decorators, you should directly add a Sphinx deprecated directive:

\n
def deprecated_function():\n    \"\"\"\n    Short description of the deprecated function.\n\n    .. deprecated:: 0.44.0\n       The function qiskit.deprecated_function() is deprecated since\n       Qiskit 0.44.0, and will be removed 3 months or more later.\n       Instead, you should use qiskit.other_function().\n\n    <rest of the docstring>\n    \"\"\"\n    # ... the rest of the function ...
\n

You should also document the deprecation in the changelog by using Reno. Explain the deprecation\nand how to migrate.

\n

In particular situations where a deprecation or change might be a major disruptor for users, a\nmigration guide might be needed. Please write these guides in Qiskit's documentation at\nhttps://github.com/Qiskit/documentation/tree/main/docs/api/migration-guides. Once\nthe migration guide is written and published, deprecation\nmessages and documentation should link to it (use the additional_msg argument for\n@deprecate_arg and @deprecate_func).

\n
","renderedFileInfo":null,"shortPath":null,"symbolsEnabled":true,"tabSize":8,"topBannersInfo":{"overridingGlobalFundingFile":false,"globalPreferredFundingPath":null,"showInvalidCitationWarning":false,"citationHelpUrl":"https://docs.github.com/github/creating-cloning-and-archiving-repositories/creating-a-repository-on-github/about-citation-files","actionsOnboardingTip":null},"truncated":false,"viewable":true,"workflowRedirectUrl":null,"symbols":{"timed_out":false,"not_analyzed":false,"symbols":[{"name":"Deprecation Policy","kind":"section_1","ident_start":2,"ident_end":20,"extent_start":0,"extent_end":13143,"fully_qualified_name":"Deprecation Policy","ident_utf16":{"start":{"line_number":0,"utf16_col":2},"end":{"line_number":0,"utf16_col":20}},"extent_utf16":{"start":{"line_number":0,"utf16_col":0},"end":{"line_number":257,"utf16_col":0}}},{"name":"Principles","kind":"section_2","ident_start":362,"ident_end":372,"extent_start":359,"extent_end":2192,"fully_qualified_name":"Principles","ident_utf16":{"start":{"line_number":7,"utf16_col":3},"end":{"line_number":7,"utf16_col":13}},"extent_utf16":{"start":{"line_number":7,"utf16_col":0},"end":{"line_number":41,"utf16_col":0}}},{"name":"What is the public interface?","kind":"section_2","ident_start":2195,"ident_end":2224,"extent_start":2192,"extent_end":4764,"fully_qualified_name":"What is the public interface?","ident_utf16":{"start":{"line_number":41,"utf16_col":3},"end":{"line_number":41,"utf16_col":32}},"extent_utf16":{"start":{"line_number":41,"utf16_col":0},"end":{"line_number":66,"utf16_col":0}}},{"name":"Removing a feature","kind":"section_2","ident_start":4767,"ident_end":4785,"extent_start":4764,"extent_end":6672,"fully_qualified_name":"Removing a feature","ident_utf16":{"start":{"line_number":66,"utf16_col":3},"end":{"line_number":66,"utf16_col":21}},"extent_utf16":{"start":{"line_number":66,"utf16_col":0},"end":{"line_number":105,"utf16_col":0}}},{"name":"Changing behavior","kind":"section_2","ident_start":6675,"ident_end":6692,"extent_start":6672,"extent_end":8571,"fully_qualified_name":"Changing behavior","ident_utf16":{"start":{"line_number":105,"utf16_col":3},"end":{"line_number":105,"utf16_col":20}},"extent_utf16":{"start":{"line_number":105,"utf16_col":0},"end":{"line_number":142,"utf16_col":0}}},{"name":"Issuing deprecation warnings","kind":"section_2","ident_start":8574,"ident_end":8602,"extent_start":8571,"extent_end":10943,"fully_qualified_name":"Issuing deprecation warnings","ident_utf16":{"start":{"line_number":142,"utf16_col":3},"end":{"line_number":142,"utf16_col":31}},"extent_utf16":{"start":{"line_number":142,"utf16_col":0},"end":{"line_number":201,"utf16_col":0}}},{"name":"Testing deprecated functionality","kind":"section_2","ident_start":10946,"ident_end":10978,"extent_start":10943,"extent_end":11718,"fully_qualified_name":"Testing deprecated functionality","ident_utf16":{"start":{"line_number":201,"utf16_col":3},"end":{"line_number":201,"utf16_col":35}},"extent_utf16":{"start":{"line_number":201,"utf16_col":0},"end":{"line_number":222,"utf16_col":0}}},{"name":"Documenting deprecations and breaking changes","kind":"section_2","ident_start":11721,"ident_end":11766,"extent_start":11718,"extent_end":13143,"fully_qualified_name":"Documenting deprecations and breaking changes","ident_utf16":{"start":{"line_number":222,"utf16_col":3},"end":{"line_number":222,"utf16_col":48}},"extent_utf16":{"start":{"line_number":222,"utf16_col":0},"end":{"line_number":257,"utf16_col":0}}}]}},"copilotInfo":null,"copilotAccessAllowed":false,"csrf_tokens":{"/Qiskit/qiskit/branches":{"post":"AnvnWEKktMl7xdDg2FvmOEu7Ehqdp_UcgO5aSr9XF15oq2Mhc0t175svTxWl5V0Yn6W54ffWT30UmFrn62QePA"},"/repos/preferences":{"post":"oo471nVhAmtVrdEew1Ubs_M8W2XI68WUbUhYknX190BtB4Z68RlLNDSSszGE-sDxEp8857z428k9HoacWCiWpg"}}},"title":"qiskit/DEPRECATION.md at main ยท Qiskit/qiskit"}