Ticket #13109: trac_13109-documentation.v3.patch

File trac_13109-documentation.v3.patch, 3.6 KB (added by vbraun, 8 years ago)

Updated patch

  • doc/en/developer/coding_in_python.rst

    # HG changeset patch
    # User Volker Braun <vbraun@stp.dias.ie>
    # Date 1339770473 -3600
    # Node ID 849f26ea378b9eaffb749942ecca936731cc3633
    # Parent  f83016231c66003fd4e9634b811a288ee64b034f
    Add a section about deprecation to the developer guide
    
    diff --git a/doc/en/developer/coding_in_python.rst b/doc/en/developer/coding_in_python.rst
    a b  
    474474controlling the top-level imports helps to do this.
    475475
    476476
     477Deprecation
     478===========
     479
     480Sooner or later you will find places in the Sage library that are, in
     481hindsight, not designed as well as they could be. Of course you want
     482to improve the overall state, but at the same time we don't want to
     483pull out the carpet under our users' feet. The process of removing old
     484code is called deprecation.
     485
     486.. note::
     487
     488    Before removing any functionality, you should keep a deprecation
     489    warning in place for at least one year (if possible). The
     490    deprecation must include the trac ticket number where it was
     491    introduced.
     492
     493For example, let's say you run across the following while working on a
     494module in the Sage library::
     495
     496    class Foo(SageObject):
     497        def terrible_idea(self):
     498            return 1
     499        def bad_name(self):
     500            return 1
     501        def f(self, weird_keyword=True):
     502            return 1
     503
     504You note that the ``terrible_idea()`` method does not make any sense,
     505and should be removed altogether. You open the trac ticket number 3333
     506(say), and replace the code with::
     507
     508        def terrible_idea(self):
     509            from sage.misc.superseded import deprecation
     510            deprecation(3333, 'You can just call f() instead')
     511            return 1
     512
     513Later, you come up with a much better name for the second method. You
     514open the trac ticket number 4444, and replace it with::
     515
     516        def much_better_name(self):
     517            return 1
     518
     519        bad_name = deprecated_function_alias(4444, much_better_name)
     520
     521Finally, you like the ``f()`` method name but you don't like the
     522``weird_keyword`` name. You fix this by opening the trac ticket 5555,
     523and replacing it with::
     524
     525        @rename_keyword(deprecation=5555, weird_keyword='nice_keyword')
     526        def f(self, nice_keyword=True):
     527            return 1
     528
     529Now, any user that still relies on the deprecated functionality will
     530be informed that this is about to change, yet the deprecated commands
     531still work. With all necessary imports, the final result looks like
     532this::
     533
     534    sage: from sage.misc.superseded import deprecation, deprecated_function_alias
     535    sage: from sage.misc.decorators import rename_keyword
     536
     537    sage: class Foo(SageObject):
     538    ...
     539    ...     def terrible_idea(self):
     540    ...             deprecation(3333, 'You can just call f() instead')
     541    ...             return 1
     542    ...
     543    ...     def much_better_name(self):
     544    ...             return 1
     545    ...
     546    ...     bad_name = deprecated_function_alias(4444, much_better_name)
     547    ...
     548    ...     @rename_keyword(deprecation=5555, weird_keyword='nice_keyword')
     549    ...     def f(self, nice_keyword=True):
     550    ...             return 1
     551
     552    sage: foo = Foo()
     553    sage: foo.terrible_idea()
     554    doctest:...: DeprecationWarning: You can just call f() instead
     555    See http://trac.sagemath.org/3333 for details.
     556    1
     557
     558    sage: foo.bad_name()
     559    doctest:...: DeprecationWarning: bad_name is deprecated. Please use much_better_name instead.
     560    See http://trac.sagemath.org/4444 for details.
     561    1
     562
     563    sage: foo.f(weird_keyword=False)
     564    doctest:...: DeprecationWarning: use the option 'nice_keyword' instead of 'weird_keyword'
     565    See http://trac.sagemath.org/5555 for details.
     566    1
     567 
     568
    477569Editing existing files
    478570======================
    479571