This is a quick guide for anyone who wants to contribute to Sage. It is intended especially for anyone who is new to computer programming. First, Sage’s main programming language is Python. Some parts of Sage can be written in other languages, especially the components that do the heavy number crunching, but most native functionality is done using Python, including “glue code”. One of the good aspects of Python that Sage inherits is that working code is considered more valuable than just fast code. Fast code is valuable, but clean, readable code is important. In the mathematics community, inaccurate results are unacceptable. Correctness comes before optimization. In the following paper
Don Knuth observes that: “We should forget about small efficiencies, say about 97% of the time: premature optimization is the root of all evil.”
If you do not know Python, you should start learning that language. A good place to start is the Python Official Tutorial and other documents in the Python standard documentation. Another good place to take a look at is Dive Into Python by Mark Pilgrim, which may be pretty helpful on some specific topics like test-driven development. The book Building Skills in Python by Steven F. Lott is suitable for anyone who is already comfortable with programming. In the meantime, you can grab your copy of the Sage source and familiarize yourself with the Mercurial source control management system. The book Mercurial: The Definitive Guide by Bryan O’Sullivan is recommended for those who want to start using Mercurial. Once you are comfortable with Python itself, which is pretty fast for basics, you can start using Sage. If you want, you can try to learn Python by using Sage, but that is not recommended because it is helpful to know what is pure Python and when Sage is doing its “magic”. There are many things that work in Python but not in Sage, and vice versa.
Then take a look at the official development guide for Sage. At a minimum, the first chapter in that guide is required reading for any Sage developer. Also pay special attention to the trac guidelines. You can also join the sage-devel mailing list and hang around on the #sage-devel IRC channel on freenode.
The best way to become familiar with the Sage development process is to choose a ticket from the trac server and review the proposed changes contained in that ticket. If you want to implement something, it is a good practice to discuss your ideas on the sage-devel mailing list first, so that other developers have a chance to comment on your ideas/proposals. They are pretty open to new ideas, too, like all mathematicians should be.
Yes. Like any free open source software project, there are numerous ways in which you could help out within the Sage community. And programming is one of many ways to contribute. If you can speak, read, and write in another (natural) language, there are many ways in which your contribution would be very valuable to the whole Sage community. Say you know Italian. Then you can write a Sage tutorial in Italian, or help out with translating the official Sage tutorial to Italian. For the graphics designers or artistically creative, you can help out with improving the design of the Sage website. Or you can cast your critical artistic eyes over the Sage notebook interface and find out where it needs improvement.
Many people like writing technical tutorials. One of the joys of doing so is that you also learn something new in the process. At the same time, you communicate your knowledge to beginners, a skill which is useful in fields other than technical writing itself. A main point about technical writing is that you communicate a technical subject to beginners, so keep technical jargons to a minimum. Darrell Anderson has written some tips on technical writing, which you are highly recommended to read. The above is a very short list. There are many, many more ways in which you can help out. Feel free to send an email to the sage-devel mailing list to ask about possible ways in which you could help out, or to suggest a project idea.
Here is an incomplete list of resources on Python and Cython. Further resources can be found by a web search.
General resources
Tutorials and books
Articles and HOWTOs
You should follow the standard Python conventions as documented at PEP 0008 and PEP 0257. Also consult the Sage Developer’s Guide, especially the chapter Conventions for Coding in Sage.
We are not trying to ignore your patch. People who work on Sage do so in their free time. With hundreds of open tickets of varying degrees of impacts on the whole Sage community, people who work on tickets need to prioritize their time and work on those tickets that interest them. Sometimes you may be the only person who understands your patch. In that case, you are encouraged to take extra care to make it as easy as possible for anyone to review your patch. Here are some tips on making your patch easy to review:
If your patch stands no chance of being merged in the Sage source tree, we will not ignore your patch but simply close the relevant ticket with an explanation why we cannot include your changes.
You are encouraged to take extra care in how you remind the Sage community of a patch you want to get merged into the Sage source tree. There might be an upcoming bug squash sprint or an upcoming Sage Days workshop that relates to your patch. Monitor the relevant Sage mailing lists and respond politely to any relevant email threads, with clear explanation on why your patch is relevant. Monitor the #sage-devel IRC channel, taking care to strategically time your reminders.
