Ticket #13109: trac_13109_documentation.patch

File trac_13109_documentation.patch, 3.4 KB (added by vbraun, 8 years ago)

Removed trailing whitespace

  • doc/en/developer/conventions.rst

    # HG changeset patch
    # User Volker Braun <vbraun@stp.dias.ie>
    # Date 1339770473 -3600
    # Node ID 20fe35e208fc46dc779907426afd00691a25a15f
    # Parent  010a1266974b4b0c4c4f8fbd0d9b20c2a9be075b
    Add a section about deprecation to the developer guide
    
    diff --git a/doc/en/developer/conventions.rst b/doc/en/developer/conventions.rst
    a b  
    659659   in the code which don't follow this advice...)
    660660
    661661
     662Deprecation
     663-----------
     664
     665Sooner or later you will find places in the Sage library that are, in
     666hindsight, not designed as well as they could be. Of course you want
     667to improve the overall state, but at the same time we don't want to
     668pull out the carpet under our user's feet. The process of removing old
     669code is called deprecation.
     670
     671.. note::
     672
     673    Before removing any functionality, you should keep a deprecation
     674    warning in place for at least one year (if possible). The
     675    deprecation must include the trac ticket number where it was
     676    introduced.
     677
     678For example, let's say you run across the following while working on a
     679module in the Sage library::
     680
     681    class Foo(SageObject):
     682        def terrible_idea(self):
     683            return 1
     684        def bad_name(self):
     685            return 1
     686        def f(self, weird_keyword=True):
     687            return 1
     688
     689You note that the ``terrible_idea()`` method does not make any sense,
     690and should be removed altogether. You open the trac ticket number 3333
     691(say), and replace the code with::
     692
     693        def terrible_idea(self):
     694            from sage.misc.superseded import deprecation
     695            deprecation(3333, 'You can just call f() instead')
     696            return 1
     697
     698Later, you come up with a much better name for the second method. You
     699open the trac ticket number 4444, and replace it with::
     700
     701        def much_better_name(self):
     702            return 1
     703
     704        bad_name = deprecated_function_alias(4444, much_better_name)
     705
     706Finally, you like the ``f()`` method name but you don't like the
     707``weird_keyword`` name. You fix this by opening the trac ticket 5555,
     708and replacing it with::
     709
     710        @rename_keyword(deprecation=5555, weird_keyword='nice_keyword')
     711        def f(self, nice_keyword=True):
     712            return 1
     713
     714With all necessary imports, the final result looks like this::
     715
     716    from sage.misc.superseded import deprecation, deprecated_function_alias
     717    from sage.misc.decorators import rename_keyword
     718
     719    class Foo(SageObject):
     720
     721        def terrible_idea(self):
     722            deprecation(3333, 'You can just call f() instead')
     723            return 1
     724
     725        def much_better_name(self):
     726            return 1
     727
     728        bad_name = deprecated_function_alias(4444, much_better_name)
     729
     730        @rename_keyword(deprecation=5555, weird_keyword='nice_keyword')
     731        def f(self, nice_keyword=True):
     732            return 1
     733
     734Now, any user that still relies on the deprecated functionality will
     735be informed that this is about to change, yet the deprecated commands
     736still work::
     737
     738    sage: foo = Foo()
     739    sage: foo.terrible_idea()
     740    DeprecationWarning: You can just call f() instead
     741    See http://trac.sagemath.org/3333 for details.
     742    1
     743
     744    sage: foo.bad_name()
     745    DeprecationWarning: bad_name is deprecated. Please use much_better_name instead.
     746    See http://trac.sagemath.org/4444 for details.
     747    1
     748
     749    sage: foo.f(weird_keyword=False)
     750    DeprecationWarning: use the option 'nice_keyword' instead of 'weird_keyword'
     751    See http://trac.sagemath.org/5555 for details.
     752    1
     753
     754
    662755Automatic testing
    663756-----------------
    664757