All changes to Sage source code have to go through the Sage Trac development server. The purpose of the Sage trac server is to
There is also a wiki for more general organizational web pages, like Sage development workshops.
Thus if you find a bug in Sage, if you have new code to submit, want to review new code already written but not yet included in Sage, or if you have corrections for the documentation, you should post on the trac server. Items on the server are called tickets, and anyone may search or browse the tickets. For a list of recent changes, just visit the Sage trac timeline.
You need a trac account if you want to change anything on the Sage trac server, even if you just want to comment on a ticket. To obtain one, send an email to sage-trac-account@googlegroups.com containing:
Your trac account also grants you access to the sage wiki. Make sure you understand the review process, and the procedures for opening and closing tickets before making changes. The remainder of this chapter contains various guidelines on using the trac server.
There are two avenues to prove to the trac server that you are who you claim to be. First, to change the ticket web pages you need to log in to trac using a username/password. Second, there is public key cryptography used by git when copying new source files to the repository. This section will show you how to setup both.
The git installation on the development server uses SSH keys to decide if and where you are allowed to upload code. No SSH key is required to report a bug or comment on a ticket, but as soon as you want to contribute code yourself you need to provide trac with the public half of your own personal key. In recent versions of Sage, you can use Sage to generate an upload an SSH key
sage: dev.upload_ssh_key()
The trac git server requires your SSH public key to be able to identify you.
Upload "/home/vbraun/.ssh/id_dsa.pub" to trac? [Yes/no] y
Trac username: user
Trac password:
Your key has been uploaded.
You can also manually generate an SSH key and upload it to trac. This is described in the following two sections.
If you don’t have a private key yet, you can create it with the ssh-keygen tool:
[user@localhost ~]$ ssh-keygen
Generating public/private rsa key pair.
Enter file in which to save the key (/home/user/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/user/.ssh/id_rsa.
Your public key has been saved in /home/user/.ssh/id_rsa.pub.
The key fingerprint is:
ce:32:b3:de:38:56:80:c9:11:f0:b3:88:f2:1c:89:0a user@localhost
The key's randomart image is:
+--[ RSA 2048]----+
| .... |
| .. |
| .o+ |
| o o+o. |
|E + . .S |
|+o . o. |
|. o +.o |
| oB |
| o+.. |
+-----------------+
This will generate a new random private RSA key in the .ssh folder in your home directory. By default, they are
The ssh-keygen tool will let you generate a key with a different file name, or protect it with a passphrase. Depending on how much you trust your own computer or system administrator, you can leave the passphrase empty to be able to login without any human intervention.
If you have accounts on multiple computers you can use the SSH keys to log in. Just copy the public key file (ending in .pub) to ~/.ssh/authorized_keys on the remote computer and make sure that the file is only read/writeable by yourself. Voila, the next time you ssh into that machine you don’t have to provide your password.
The Sage trac server needs to know one of your public keys. You can upload it in the preferences, that is
Note that this does not allow you to ssh into any account on trac, it is only used to authenticate you to the gitolite installation on trac. You can test that you are being authenticated correctly by issuing some basic gitolite commands, for example:
[user@localhost ~]$ ssh git@trac.sagemath.org info
hello user, this is git@trac running gitolite3 (unknown) on git 1.7.9.5
R W sage
[user@localhost ~]$ ssh git@trac.sagemath.org help
hello user, this is gitolite3 (unknown) on git 1.7.9.5
list of remote commands available:
desc
help
info
perms
writable
If you think you have found a bug in Sage, here is the procedure:
Search through our Google groups for postings related to your possible bug (it may have been fixed/reported already):
Similarly, you can search The Sage Trac Server to see if anyone else has opened a ticket about your bug.
If you do not find anything, and you are not sure that you have found a bug, ask about it on sage-devel. A bug report should contain:
You might be asked to open a new ticket. In this case, follow the Guidelines for Opening Tickets.
Thank you in advance for reporting bugs to improve Sage in the future!
In addition to bug reports (see Reporting Bugs), you should also open a ticket if you have some new code that makes Sage a better tool. If you have a feature request, start a discussion on sage-devel first, and then if there seems to be general agreement that you have a good idea, open a ticket describing the idea.
Before opening a new ticket, consider the following points:
When creating the ticket, you may find useful to read The Ticket Fields.
Unless you know what you are doing, leave the milestone field to its default value.
When you open a new ticket or change an existing ticket, you will find a variety of fields that can be changed. Here is a comprehensive overview (for the ‘status’ field, see The status of a ticket):
The status of a ticket appears right next to its number, at the top-left corner of its page. It indicates who has to work on it.
new – the ticket has only been created (or the author forgot to change the status to something else).
If you want to work on it yourself it is better to leave a comment to say so. It could avoid having two persons doing the same job.
needs_review – the code is ready to be peer-reviewed. If the code is not yours, then you can review it. See The reviewer’s check list.
needs_work – something needs to be changed in the code. The reason should appear in the comments.
needs_info – somebody has to answer a question before anything else can happen. It should be clear from the comments.
positive_review – the ticket has been reviewed, and the release manager will close it.
The status of a ticket can be changed using a form at the bottom of the ticket’s page. Leave a comment explaining your reasons whenever you change it.
When Sage returns wrong results, two tickets should be opened:
This second ticket does not fix the problem but adds a warning that will be printed whenever anyone uses the relevant code. This, until the problem is finally fixed.
To produce the warning message, use code like the following:
from sage.misc.stopgap import stopgap
stopgap("This code contains bugs and may be mathematically unreliable.",
TICKET_NUM)
Replace TICKET_NUM by the ticket number for the main ticket. On the main trac ticket, enter the ticket number for the stopgap ticket in the “Stopgaps” field (see The Ticket Fields). Stopgap tickets should be marked as blockers.
Note
If mathematically valid code causes Sage to raise an error or crash, for example, there is no need for a stopgap. Rather, stopgaps are to warn users that they may be using buggy code; if Sage crashes, this is not an issue.
If you manage to fix a bug or enhance Sage you are our hero. See Sage Development Process for making changes to the Sage source code, uploading them to the Sage trac server, and finally putting your new branch on the trac ticket. The following are some other relevant issues:
Tickets can be closed when they have positive review or for other reasons. To learn how to review, please see The reviewer’s check list.
Only the Sage release manager will close tickets. Most likely, this is not you nor will your trac account have the necessary permissions. If you feel strongly that a ticket should be closed or deleted, then change the status of the ticket to needs review and change the milestone to sage-duplictate/invalid/wontfix. You should also comment on the ticket, explaining why it should be closed. If another developer agrees, he sets the ticket to positive review.
A related issue is re-opening tickets. You should refrain from re-opening a ticket that is already closed. Instead, open a new ticket and provide a link in the description to the old ticket.
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 lines 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 tarball 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.
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.