நிராகரிப்பு கொள்கை#

பல பயனர்கள் மற்றும் பிற தொகுப்புகள் Qiskit இன் வெவ்வேறு பகுதிகளைச் சார்ந்துள்ளது. குறியீட்டில் மாற்றங்களைச் செய்யும்போதெல்லாம், பயனர்கள் ஏற்கனவே எழுதிய குறியீட்டை உடைக்காமல் சரிசெய்ய போதுமான நேரத்தை வழங்குகிறோம் என்பதை உறுதிசெய்ய வேண்டும்.

மிக முக்கியமாக: பொது முகமாக இருக்கும் எந்த இடைமுகத்தையும் நாம் கண்டிப்பாக மாற்ற வேண்டியதில்லை. விஷயங்களைச் சேர்ப்பது பரவாயில்லை, பொருட்களை எடுத்துச் செல்வது பயனர்களுக்கு எரிச்சலூட்டும், ஆனால் பல அறிவிப்புகளுடன் நியாயமான முறையில் கையாளப்படலாம், ஆனால் நடத்தையை மாற்றுவது பொதுவாக Qiskit இன் இரண்டு அடுத்தடுத்த பதிப்புகளுடன் செயல்படும் குறியீட்டை எழுத முடியாது, இது ஏற்றுக்கொள்ள முடியாதது.

பயனர்கள் பெரும்பாலும் செயல்பாடுகள், வகுப்புகள் மற்றும் முறைகளைப் பயன்படுத்துவார்கள் என்பதில் கவனமாக இருங்கள் "இது புதைக்கப்பட்டுள்ளது, எனவே யாரும் இதைப் பயன்படுத்த மாட்டார்கள்" என்று அனுமானங்களைச் செய்ய வேண்டாம்; பொது என்றால் அது கொள்கைக்கு உட்பட்டது. இங்குள்ள ஒரே விதிவிலக்குகள் செயல்பாடுகள் மற்றும் தொகுதிகள் வெளிப்படையாக உள், அதாவது முன்னணி அடிக்கோடிடுடன் தொடங்கும் பெயர்கள் (_).

வழிகாட்டும் கொள்கைகள்:

குறைந்தது மூன்று மாதங்கள் அல்லது இரண்டு முழுமையான பதிப்பு சுழற்சிகளுக்குச் செயலில் உள்ள எச்சரிக்கைகள் இல்லாமல் குறியீட்டை அகற்றவோ மாற்றவோ கூடாது;
எந்த எச்சரிக்கையையும் வெளியிடாத சரியான இலக்குகளை அடைய எப்போதும் ஒரு வழி இருக்க வேண்டும்;
வெளிப்படையாக உள்நாட்டில் இல்லாத ஒரு செயல்பாடு பயன்பாட்டில் இல்லை என்று ஒருபோதும் கருத வேண்டாம்;
அனைத்து நீக்குதல்கள், மாற்றங்கள் மற்றும் அகற்றுதல்கள் API மாற்றங்களாகக் கருதப்படுகின்றன, மேலும் சிறு வெளியீடுகளில் மட்டுமே நிகழலாம், பேட்ச் வெளியீடுகள் அல்ல, stable கிளைக் கொள்கை.

ஒரு அம்சத்தை நீக்குகிறது#

ஒரு அம்சத்தை அகற்றும்போது (உதாரணமாக ஒரு வகுப்பு, செயல்பாடு அல்லது செயல்பாட்டு அளவுரு), நாங்கள் இந்த நடைமுறையைப் பின்பற்றுவோம்:

ஏதேனும் எச்சரிக்கைகள் வழங்கப்படுவதற்கு முன், ஒரு சிறிய பதிப்பிற்கான மாற்று பாதை இருக்க வேண்டும். எடுத்துக்காட்டாக, foo() செயல்பாட்டை bar() உடன் மாற்ற விரும்பினால், foo() க்குள் ஏதேனும் எச்சரிக்கைகளை வழங்குவதற்கு முன், இரண்டு செயல்பாடுகளுடன் குறைந்தபட்சம் ஒரு வெளியீட்டையாவது செய்ய வேண்டும். பழைய பாதைகளில் இருந்து ``நிலுவையில் உள்ள தேய்மான எச்சரிக்கை```களை உடனடியாக வழங்கலாம்.

காரணம்: மக்கள் மேம்படுத்தியவுடன் அவர்களின் குறியீட்டை உடைக்காமல் மாற்றிக்கொள்ள அவர்களுக்கு நேரம் கொடுக்க வேண்டும்.
குறைந்தபட்சம் ஒரு சிறிய பதிப்பிற்கு மாற்று பாதை அமைக்கப்பட்ட பிறகு, தேக்கநிலை எச்சரிக்கைகளை வழங்கவும். அனைத்து நீக்கப்பட்ட பாதைகள், அவற்றின் மாற்றுகள் மற்றும் தேய்மானத்திற்கான காரணத்தை பட்டியலிடும் தேக்கங்கள் பிரிவுடன் வெளியீட்டுக் குறிப்பைச் சேர்க்கவும். <testing-deprecated-functionality> எச்சரிக்கைகளைச் சோதிக்க சோதனைகளைப் புதுப்பிக்கவும்.

காரணம்: பயனர்கள் உண்மையில் செல்லும்போது ஆச்சரியப்படுவதைக் குறைக்க, குறைந்தபட்சம் ஒரு பதிப்பிலாவது அகற்றுதல்கள் அதிகமாகத் தெரியும்.
பழைய அம்சத்திற்கு அகற்றும் தேதியை அமைத்து, அதை (மற்றும் எச்சரிக்கைகள்) அடைந்ததும் அகற்றவும். எச்சரிக்கையுடன் கூடிய பதிப்பு முதலில் வெளியிடப்பட்டு குறைந்தது மூன்று மாதங்களுக்குப் பிறகு இது இருக்க வேண்டும், மேலும் எச்சரிக்கைகளுக்குப் பிறகு உடனடியாக சிறிய பதிப்பாக இருக்க முடியாது. அனைத்து நீக்குதல்களையும் பட்டியலிடும் மேம்படுத்து வெளியீட்டுக் குறிப்பைச் சேர்க்கவும். எடுத்துக்காட்டாக, 0.19.0 இல் மாற்றுப் பாதை வழங்கப்பட்டு, எச்சரிக்கைகள் 0.20.0 இல் சேர்க்கப்பட்டால், 0.21 ஆக இருந்தாலும், அகற்றுவதற்கான முந்தைய பதிப்பு ``0.22.0 ஆகும். 0.20.0``க்குப் பிறகு மூன்று மாதங்களுக்கும் மேலாக. 0 வெளியிடப்பட்டது.

Note

இவை குறைந்தபட்ச தேவைகள். குறிப்பிடத் தக்க அல்லது முக்கிய அம்சங்களை அகற்ற, பயனர்களுக்குக் குறைந்தபட்சம் கூடுதல் சிறிய பதிப்பை வழங்கவும்.

காரணம்: பயனர்கள் இந்தச் செய்திகளைப் பார்ப்பதற்கும், அவற்றைச் சரிசெய்ய அவர்களுக்கு நேரம் ஒதுக்குவதற்கும் நேரம் இருக்க வேண்டும். அனைத்து பயனர்களும் தங்கள் Qiskit பதிப்பை உடனடியாகப் புதுப்பிக்கமாட்டார்கள், மேலும் சிலர் சிறிய பதிப்புகளைத் தவிர்க்கலாம்.

காரணம்: பயனர்கள் இந்தச் செய்திகளைப் பார்ப்பதற்கு, அவற்றைச் சரிசெய்ய அவர்களுக்கு நேரம் ஒதுக்குவதற்கு நேரம் இருக்க வேண்டும். அனைத்து பயனர்களும் Qiskit பதிப்பை உடனடியாகப் புதுப்பிக்கமாட்டார்கள், மேலும் சிலர் சிறிய பதிப்புகளைத் தவிர்க்கலாம்.

நடத்தையை மாற்றுதல்#

அகற்றப்படாமல் நடத்தையை மாற்றுவது நிர்வகிப்பது மிகவும் கடினம், ஏனென்றால் இரண்டு பதிப்புகளுக்கு இரண்டு விருப்பங்களும் இருக்க வேண்டும், மேலும் எச்சரிக்கைகளை வழங்க முடியும். எடுத்துக்காட்டாக, ஒரு செயல்பாட்டிலிருந்து திரும்பும் மதிப்பின் வகையை மாற்றுவது ஏறக்குறைய ஒரு API இடைவேளையை உள்ளடக்கும், இது பயனர்களுக்கு வெறுப்பை ஏற்படுத்துகிறது மற்றும் அவர்கள் Qiskit ஐப் பயன்படுத்துவதை கடினமாக்குகிறது.

இங்கே சிறந்த தீர்வாகப் பெரும்பாலும் ஒரு புதிய செயல்பாட்டை உருவாக்கி, பின்னர் :ref: மேலே உள்ள <removing-features>` அகற்றுவதற்கான நடைமுறைகளைப் பயன்படுத்தவும்.

ஏற்கனவே உள்ள குறியீட்டின் நடத்தையை நீங்கள் முற்றிலும் மாற்ற வேண்டும் என்றால் (பிழைகளை சரிசெய்வதைத் தவிர), இந்த ஆவணத்தின் மேலே உள்ள வழிகாட்டும் கொள்கைகளைப் பயன்படுத்த உங்கள் சிறந்த தீர்ப்பைப் பயன்படுத்த வேண்டும். நடத்தை மாற்றங்களுக்கு மிகவும் பொருத்தமான எச்சரிக்கை பொதுவாக FutureWarning ஆகும். மாற்றத்தை எவ்வாறு செயல்படுத்துவது என்பதற்கான சில சாத்தியங்கள்:

செயல்பாட்டின் இயல்புநிலை நடத்தையை நீங்கள் மாற்றினால், பழைய மற்றும் புதிய நடத்தைகளுக்கு இடையே தேர்ந்தெடுக்க ஒரு முக்கிய வாதத்தைச் சேர்ப்பதைக் கவனியுங்கள். நேரம் வரும்போது, புதிய மதிப்பு விரைவில் இயல்புநிலையாக மாறும் என்று கூறி, முக்கிய வாதம் வழங்கப்படாவிட்டால் (எ.கா. அது None) எனில், நீங்கள் FutureWarning வழங்கலாம். நீங்கள் நடத்தை மாற்றத்தை செய்த பிறகு, இந்த முக்கிய வார்த்தை வாதத்தை அகற்ற, நீங்கள் சாதாரண தேய்மான காலத்தை கடக்க வேண்டும். இரண்டு சுழற்சிகளையும் கடந்து செல்ல குறைந்தது ஆறு மாதங்கள் ஆகும்.
நீங்கள் செயல்பாட்டின் திரும்பும் வகையை மாற்ற வேண்டும் என்றால், புதிய வகையை வழங்கும் புதிய செயல்பாட்டைச் சேர்ப்பதைக் கருத்தில் கொள்ளவும், பின்னர் பழைய செயல்பாட்டை நிறுத்துவதற்கான நடைமுறைகளைப் பின்பற்றவும்.
புதிய உள்ளீட்டை அதன் வகையின் காரணமாக வேறுபடுத்திப் பார்க்க முடியாத ஒரு புதிய உள்ளீட்டை நீங்கள் ஏற்க வேண்டும் என்றால், அதை வேறு முக்கிய வாதத்தின் மூலம் அனுப்ப அனுமதிக்கவும் அல்லது புதிய படிவத்தை மட்டுமே ஏற்கும் இரண்டாவது செயல்பாட்டைச் சேர்க்கவும்.

பணிநீக்கம் எச்சரிக்கைகளை வழங்குதல்#

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

from qiskit.utils.deprecation import deprecate_arg, deprecate_func

@deprecate_func(since="0.24.0", additional_msg="No replacement is provided.")
def deprecated_func():
    pass

@deprecate_arg("bad_arg", new_alias="new_name", since="0.24.0")
def another_func(bad_arg: str, new_name: str):
    pass

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

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

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

import warnings

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

தேய்மான எச்சரிக்கையை அறிமுகப்படுத்திய தொகுப்பின் பதிப்பை நீங்கள் சேர்த்துள்ளீர்கள் என்பதை உறுதிப்படுத்திக் கொள்ளுங்கள் (எனவே, அதை அகற்றுவது எப்போது செல்லுபடியாகும் என்பதை பராமரிப்பாளர்கள் எளிதாகக் காணலாம்), மற்றும் மாற்று வழி என்ன.

ஸ்டாக்லெவல் வாதத்தை கவனத்தில் கொள்ளவும். எந்த செயல்பாடு தடுக்கப்பட்டது என்று குற்றம் சாட்டப்படுவதை இது கட்டுப்படுத்துகிறது. stacklevel=1 (இயல்புநிலை) அமைப்பதன் அர்த்தம், எச்சரிக்கையானது warn செயல்பாட்டையே குற்றம் சாட்டும், அதேசமயம் stacklevel=2` சரியாகக் கொண்டிருக்கும் செயல்பாட்டைக் குற்றம்சாட்டும். இதை 2 என்பதைத் தவிர வேறு எதற்கும் அமைப்பது வழக்கத்திற்கு மாறானது, ஆனால் பல இடங்களில் ஒரே எச்சரிக்கையை வழங்குவதற்கு உதவி செயல்பாட்டைப் பயன்படுத்தினால் பயனுள்ளதாக இருக்கும்.

நிறுத்தப்பட்ட செயல்பாட்டைச் சோதிக்கிறது#

நீக்குதல் எச்சரிக்கைகளைச் சேர்க்கும் போதெல்லாம், செயல்பாடு சம்பந்தப்பட்ட சோதனைகளை நீங்கள் புதுப்பிக்க வேண்டும். புதிய எச்சரிக்கைகள் காரணமாக சோதனைத் தொகுப்பு இல்லையெனில் தோல்வியடையும். அது இன்னும் செயல்படுகிறதா என்பதை உறுதிசெய்ய, தேய்மானக் காலம் முழுவதும் நிறுத்தப்பட்ட செயல்பாட்டை நாங்கள் தொடர்ந்து சோதிக்க வேண்டும்.

சோதனைகளைப் புதுப்பிக்க, நிராகரிக்கப்பட்ட நடத்தையின் ஒவ்வொரு அழைப்பையும் அதன் சொந்த வலியுறுத்தல் தொகுதியில் மடிக்க வேண்டும். துணைப்பிரிவுகளுக்கு unittest.TestCase (அனைத்து Qiskit சோதனை நிகழ்வுகளும்), இது இவர்களால் செய்யப்படுகிறது:

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

நிராகரிப்பு மற்றும் மாற்றங்களை உடைத்தல் ஆகியவற்றை ஆவணப்படுத்துதல்#

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

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

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

.. code-block:: python

def deprecated_function():
""" Short description of the deprecated function.

Deprecated since version 0.20.0: The function qiskit.deprecated_function() is deprecated since Qiskit Terra 0.20.0, and will be removed 3 months or more later. Instead, you should use qiskit.other_function().

<rest of the docstring> """ # ... the rest of the function ...

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

In particular situations where a deprecation or change might be a major disruptor for users, a migration guide might be needed. Once the migration guide is written and published, deprecation messages and documentation should link to it (use the additional_msg: str argument for @deprecate_arg and @deprecate_func).