FAQ: Contributing to Sage#

How can I start contributing to Sage?#

The first step is to use Sage and encourage your friends to use Sage. If you find bugs or confusing documentation along the way, please report your problems!

Two popular ways to contribute to Sage are to write code and to create documentation or tutorials. Some steps in each direction are described below.

I want to contribute code to Sage. How do I get started?#

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 GitHub guidelines. You can also join the sage-devel mailing list or hang around on the SageMath Zulip chat channel. While you are getting to know the community, grab a copy of the Sage source and familiarize yourself with the git version control system.

The best way to become familiar with the Sage development process is to choose an issue from the Sage repository on GitHub and review the proposed changes contained in that issue. 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, as all mathematicians should be.

Sage’s main programming language is Python. Some parts of Sage may 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 merely 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

D. Knuth. Structured Programming with go to Statements. ACM Journal Computing Surveys, 6(4), 1974.

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 such as test-driven development. The book Building Skills in Python by Steven F. Lott is suitable for anyone who is already comfortable with programming.

If you want, you can try to learn Python by using Sage. However, 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. Furthermore, even when the syntax is identical, many programming concepts are explained more thoroughly in Python-centered resources than in Sage-centered resources; in the latter, mathematics is usually the priority.

I am not a programmer. Is there another way I can help out?#

Yes. As with any free open source software project, there are numerous ways in which you could help out within the Sage community, and programming is only one of many ways to contribute.

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 jargon to a minimum. Darrell Anderson has written some tips on technical writing, which we highly recommend.

For the graphic designers or the artistically creative, you can help out with improving the design of the Sage website.

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.

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.

Where can I find resources on Python or Cython?#

Here is an incomplete list of resources on Python and Cython. Further resources can be found by a web search.

General resources

Cython
pep8
pydeps
pycallgraph
PyChecker
PyFlakes
Pylint
Python home page and the Python standard documentation
Snakefood
Sphinx
XDot

Tutorials and books

Cython Tutorial by Stefan Behnel, Robert W. Bradshaw, and Dag Sverre Seljebotn
Dive Into Python 3 by Mark Pilgrim
Fast Numerical Computations with Cython by Dag Sverre Seljebotn
Official Python Tutorial

Articles and HOWTOs

decorator
Functional Programming HOWTO by A. M. Kuchling
Python Functional Programming for Mathematicians by Minh Van Nguyen
Regular Expression HOWTO by A. M. Kuchling
reStructuredText

Are there any coding conventions I need to follow?#

You should follow the standard Python conventions as documented at PEP 8 and PEP 257. Also consult the Sage Developer’s Guide, especially the chapter Conventions for Coding in Sage.

I submitted a bug fix to the GitHub Sage repo several weeks ago. Why are you ignoring my branch?#

We are not trying to ignore your branch. Most people who work on Sage do so in their free time. With hundreds of open PRs of varying degrees of impacts on the whole Sage community, people who work on PRs need to prioritize their time and work on those PRs that interest them. Sometimes you may be the only person who understands your branch. In that case, you are encouraged to take extra care to make it as easy as possible for anyone to review. Here are some tips on making your branch easy to review:

Have you clearly described the problem your branch is trying to solve?
Have you provided any background information relevant to the problem your patch is trying to solve? Such information include links to online resources and any relevant papers, books and reference materials.
Have you clearly described how your branch solves the problem under consideration?
Have you clearly described how to test the changes in your branch?
Have you listed any issues/PRs that your branch depends on?
Is your branch based on a recent (preferably, the latest) Sage beta version?
Does your branch follow relevant conventions as documented in the Developer’s Guide?

If your branch stands no chance of being merged in the Sage source tree, we will not ignore your branch but simply close the relevant PR with an explanation why we cannot include your changes.

When and how might I remind the Sage community of a branch I care about?#

You are encouraged to take extra care in how you remind the Sage community of a branch/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.

I wrote some Sage code and I want it to be integrated into Sage. However, after renaming my file `a.sage` to `a.py`, I got syntax errors. Do I have to rewrite all my code in Python instead of Sage?#

The basic answer is yes, but rewriting is a big word for what is really needed. There is little work to do since Sage mostly follows Python syntax. The two main differences are handling of integer (see also the afterword for more on the sage preparser), and the necessity to import what you need.

Handling of integers: You need to take care of the following changes:
- Notation for exponentiation: In Python ** means exponentiation and ^ means “xor”.
- If you need to return an integer to the user, write return Integer(1) instead of return 1. In Python, 1 is a python int, and Integer(1) is a Sage/Gmp integer. In addition, Integer are much more powerful than int; for example, they know about being prime and factorization.
- You should also notice that 2 / 3 no longer means Integer(2) / Integer(3) and returns 2/3, but rather int(2) / int(3), and therefore returns 0 due to integer division where it deregards any remainder. If you are dealing with Integer but you really need an integer division you can use Integer(2) // Integer(3).

Importing stuff: The second big change is the necessity to import everything what you need. More precisely, each time you use some Sage function, you need to import it at the beginning of the file. For example, if you want PolynomialRing, you need to write:

from sage.rings.polynomial.polynomial_ring_constructor import PolynomialRing

You can use import_statements to get the exact necessary line:

Sage

sage: import_statements(PolynomialRing)
from sage.rings.polynomial.polynomial_ring_constructor import PolynomialRing

Python

>>> from sage.all import *
>>> import_statements(PolynomialRing)
from sage.rings.polynomial.polynomial_ring_constructor import PolynomialRing

If this fails, you can ask Sage where to find PolynomialRing using: