Trac Guidelines for Sage
Requesting a Trac Account
To prevent spam, we have had to disable anonymous creation and editing of tickets. Please check the details here: http://trac.sagemath.org/sage_trac/. The account name should be non-silly, i.e. no first names, no leet-handles. Ideally it should be the first character of your first name together with your last name. It is also recommended that it should be identical or at least close to your Google group's handle. The password currently cannot be changed by the user.
Also, be sure to add your account name and info to the front page of http://trac.sagemath.org/
Anonymous Bug Reports
If you don't have an account at the trac system to report directly, don't worry! You are still encouraged to report any possible bug to:
the sage-devel mailing list at <email@example.com> [the list is moderated for new users and requires subscription]
or email directly to: firstname.lastname@example.org. Please make sure that the subject contains [Sage Bug Report] since that address receives a lot of spam.
In both cases make sure to include:
operating system, as precise as possible and architecture (32-bit, 64-bit, ...)
affected version: the exact version number and the downloaded package (source, precompiled, image or an upgrade from a previous version (which one?))
provide a reproducible example and/or define the steps to reproduce the erroneous behaviour.
Thank you in advance for reporting bugs to improve Sage in the future!
- Before opening a ticket, make sure that nobody else has opened a ticket about the same or closely related issue.
- It is better to open several specific tickets than one that is very broad.
- Be precise: If foo doesn't work on OSX, but is fine on Linux, mention that in the title. Also use the keyword option to make searches pick up the issue.
Be careful with the priority: blocker should be used sparingly; don't be surprised that such a ticket is reclassified. On the other hand, tickets that one might consider to be of non-blocker quality might be promoted. When in doubt, write an email to sage-devel or ask around on #sage-devel.
100% Doctests: All 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.
Test the reference manual: sage -docbuild reference html must produce no errors
Test the Sage library: make test or make ptest (edit number of threads in makefile before using ptest!)
Reasons To Invalidate Trac Tickets
One Issue Per Ticket: A 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 (e.g. 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 (e.g. pari, GAP, lisp, gmp), it is no longer a problem that belongs in our tracker. If your 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 to be 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.
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. An example would be to "Make Sage the best CAS in the world". There is no metric to measure this properly and it is highly subjective. The ultimate goal of Sage development is world domination, but please don't open a ticket for that.
Milestones vs. Releases
- Milestones are usually goals to be met while working toward a release. In Sage's trac, we use milestones instead of releases, but unless somebody volunteers to clean up all the old milestones, we will stick with the current model. It doesn't make a whole lot of difference if we use milestone instead of release.
- Finely grained releases are good. Release early and often is the way to go, especially as more and more patches are coming in.
- It is a good idea to make a big release and schedule at least one more bugfix release after that to sort out the inevitable "doctest X is broken on distribution Y and compiler Z" problem. Given the number of compilers and operating systems out there, one has to be realistic to expect problems. A compile farm would certainly help to catch issues early.
- Each ticket must have a milestone assigned.
- If a ticket has a patch or spkg that is ready to be reviewed, assign it against the current milestone.
- defect vs. enhancement vs. task: this can be tricky, but a defect should be something that leads to an exception or a mathematically wrong result.
If you are unsure to whom to assign the ticket, assign it to somebody.
Certain categories have default people that get assign all issues. One example is mabshoff for memory leaks.
If you have been assigned a ticket, you should either accept it or assign it back to somebody or tba. Many people do not accept pending tickets at the moment. You have accepted a ticket if your name has a star next to it.
Working On Tickets
Every bug fixed should result in a doctest. Example: zombie det() problem with LinBox, considered fixed twice, but reopened in both cases.
- Cooperative debugging via IRC is faster by at least an order of magnitude. If you haven't learned how to use IRC, please do so. If you have problems using IRC because of firewalls, but you do have an account on sage.math, you can use irssi via ssh there. If you have a flaky connection, you can use it together with screen.
- This is not an issue with defects, but there are many enhancements possible for Sage and too few developers to implement all the good ideas. But it is useful to keep ideas in a central place because in the Google groups they tend to get lost once they drop off the first page.
- If you are a developer, be nice and try to solve a stale/old ticket every once in a while.
- Some people regularly do triage, especially before Bug Days. Triage in this context means that we look at new bugs and classify them according to our perceived priority. It is very likely that different people will see priorities of bugs very differently from us, so please let us know if you see a problem with specific tickets.
Patches Preferred: Patches are easier to review, edit and can be merged without affecting the history. So we greatly prefer patches over mercurial bundles. If you do have a large number of patches, a bundle can still be better than patches. One alternative to bundles is to use Mercurial queues to flatten the history. That might or might not be desirable.
It would be nice to add something about our conventions about titles; "[with patch, needs review]", and so on. Also, what exactly must be done to review a patch? I'd like to see more about this. --DanDrake
Based on recent mailing list discussion, there appears to be a standard for naming patches: trac_NNNN_name. If this is going to be preferred/required, it should be stated here. --PeterJeremy
What are the conventions regarding including people listed as spkg maintainers and/or upstream contacts in tickets? This needs to be documented here. --PeterJeremy