Changes between Version 24 and Version 25 of CompatibilityPolicy

10/17/2013 01:55:36 AM (5 years ago)

Procedure for incompatible changes.


  • CompatibilityPolicy

    v24 v25  
    8989Removal should happen once the deprecated API becomes an additional maintenance burden.  For example, if it makes implementation of a new feature more difficult, if it makes documentation of non-deprecated APIs more confusing, or if its unit tests become an undue burden on the continuous integration system.  Removal should not be undertaken just to follow a timeline.  Twisted should strive, as much as practical, not to break applications relying on it.
     91=== Procedure for Exceptions to this Policy ===
     93Every change is unique.  Sometimes, we'll want to make a change that fits with this spirit of this document (keeping Twisted working for applications which rely upon it) but may not fit with the letter of the procedure described above (the change modifies behavior of an existing API sufficiently that something ''might'' break).  Generally, the reason that one would want to do this is to give applications a performance enhancement or bug fix that ''could'' break behavior that  unanticipated, hypothetical uses of an existing API, but we don't want well-behaved applications to pay the penalty of a deprecation/adopt-a-new-API/removal cycle in order to get the benefits of the improvement if they don't need to.
     95If this is the case for your change, it's possible to make such a modification without a deprecation/removal cycle.  However, we must give users an opportunity to discover whether a particular incompatible change affects them: we should not trust our own assessments of how code uses the API.  In order to propose an incompatible change, start a discussion on the mailing list.  Make sure that it is eye-catching so those who don't read all list messages in depth will notice it, by prefixing the subject with "INCOMPATIBLE CHANGE:" (capitalized like so).  Always include a link to the ticket, and branch (if relevant).
     97In order to '''conclude''' such a discussion, there must be a branch available so that developers can run their unit tests against it to mechanically verify that their understanding of their own code is correct.  If nobody can produce a failing test or broken application within a week's time from such a branch being both 1. available and 2. announced, and at least three committers agree that the change is worthwhile, then the branch can be considered approved for the incompatible change in question.  (Since some codebases that use Twisted are presumably proprietary and confidential, there should be a good-faith presumption if someone says they have broken tests but cannot immediately produce code to share.)  The branch must be available for one week's time.
     99(The announcement forum for incompatible changes and the waiting period required are subject to change as we discover how effective this method is; the important aspect of this policy is that users have some way of finding out in advance about changes which might affect them.)
    91101== Application Developer Upgrade Procedure ==