Ticket #12702: trac_12702-doc.patch

File trac_12702-doc.patch, 1.6 KB (added by jhpalmieri, 7 years ago)
  • doc/en/developer/trac.rst

    # HG changeset patch
    # User J. H. Palmieri <palmieri@math.washington.edu>
    # Date 1332197812 25200
    # Node ID 8c60166f2a1e84e99717a2e7cb31ddb29e30730a
    # Parent  1b72e2de22a043c544100872cf30370be1618502
    Document stopgaps
    
    diff --git a/doc/en/developer/trac.rst b/doc/en/developer/trac.rst
    a b points in mind. 
    122122  threads relevant to the problem you are reporting.
    123123
    124124
     125Stopgaps
     126========
     127
     128If a component of Sage produces a mathematical error, you should open
     129two tickets: a main ticket with all available details, and also a
     130"stopgap" ticket. This second ticket should have a patch which will be
     131merged into Sage if no one fixes the main issue; this patch should print a
     132warning when anyone uses the relevant code. To produce the warning
     133message, use code like the following::
     134
     135    from sage.misc.stopgap import stopgap
     136    stopgap("This code contains bugs and may be mathematically unreliable.",
     137        TICKET_NUM)
     138
     139Replace ``TICKET_NUM`` by the ticket number for the main ticket.  See
     140:trac:`12699`, for example.  On the main trac ticket, you should also
     141enter the ticket number for the stopgap ticket in the "Stopgaps"
     142field.  Stopgap tickets should be marked as blockers.
     143
     144.. note::
     145
     146    If mathematically valid code causes Sage to raise an error or
     147    crash, for example, there is no need for a stopgap.  Rather,
     148    stopgaps are to warn users that they may be using buggy code; if
     149    Sage crashes, this is not an issue.
     150
     151
    125152Patching bugs/working on tickets
    126153================================
    127154