Trac Guidelines for Sage

Trac Tickets

Rules

• One Issue Per Ticket: Ticket must cover only one issue and should not be a laundry list of unrelated issues. If a ticket covers more than one issue we cannot close it and while some of the patches have been applied to a given release the ticket would remain in limbo.

• No Patch Bombs: Code that goes into Sage is peer reviewed. If you show up with an 80,000 line of code bundle that completely rips out a subsystem and replaces it with something else you can imagine that the review process will be a little tedious. These huge patch bombs are problematic for several reasons and we prefer small, gradual changes that are easy to review and apply. This is not always possible [coercion rewrite], but it is still highly recommended that you avoid this style of development unless there is no way around it.

• Sage Specific: Sage's philosophy is that we ship everything [or close to it] in one source ball to make debugging possible. You can imagine the combinatorial explosion we would have to deal with if you replaced only ten components of Sage with external packages. Once you start replacing some of the more essential components of Sage that are commonly packaged [pari, GAP, lisp, gmp] it is no longer a problem that belongs in our tracker. If you distribution's pari package is buggy for example file a bug report with them. We are usually willing and able to solve the problem, but there are no guarantees that we will help you out. Looking at the open number of tickets that are Sage specific you hopefully will understand why.

• No Support Discussions: The trac installation is not meant a system to track down problems when using Sage. Tickets should be clearly a bug and not "I tried to do X and I couldn't get it to work. How do I do this". That is usually not a bug in Sage and it is likely that sage-support can answer that question for you. If it turns out that you did hit a bug somebody will open a concise and to the point ticket.

• No Closing Or Invalidating: Unless you have admin powers in trac [which includes all the people who have ever done releases of Sage] do not close tickets unless you are explicitly told to do so. Since we have email notification now this has become less of an issue. If you think that a ticket is invalid or has been fixed just comment on it and the current release manager will take a look and close it if appropriate. On exception to this rule is if you happen to open the same ticket multiple times in a row. Feel free to close the extras in that case.

• Solution Must Be Achievable: Tickets must be achievable. Many times tickets that fall into this category usually ran afoul to some of the other rules listed above. A an example would be to "Make Sage the best CAS in the world".

Recommendations

• Patches Preferred:

Reviewing Patches

• 100% Doctests: New code must be 100% doctested. There is no way around this.

• Bug Fixes Must Be Doctested: The patch that fixes an issue must also contain a doctest specifically to test the problem. This is not always possible, so this is not enforced in certain situations.