If you are editing or adding to Sage’s core library, you will probably want to share your changes with other users. Mercurial is the tool to do this. Mercurial is the source control system that is included with Sage. This chapter provides an overview of how to use Mercurial with Sage; see http://www.selenic.com/mercurial/ for full documentation on Mercurial.
All of the Mercurial repositories related to Sage are included with Sage. Thus the complete change history and setup for doing development is available in your copy of Sage.
Before using Mercurial, make sure to define your username so the patches you make are identified as yours. Make a file ~/.hgrc in your home directory like this one:
[ui]
username = Cardinal Fang <fang@spanish-inquisition.com>
There are several ways to run Mercurial: from the command line, run sage -hg (Hg is the chemical symbol for mercury), or from within Sage, run hg_sage. Most of the examples below use the second method.
Before you modify Sage library files, you might want to create a copy of the Sage library in which to work. Do this by typing sage -clone myver, for example; then Sage will use Mercurial to clone the current repository and call the result myver. The new repository is stored in <SAGE_ROOT>/devel/sage-myver, and when you clone, the symlink sage --> sage-myver is made.
(You can also do, e.g., sage -clone -r 1250 oldver, to get a clone of Sage as it was at revision 1250. Of course, dependency issues could make old versions not work (e.g., maybe an old Sage library won’t compile with the latest Singular library, which is what is installed elsewhere in SAGE_ROOT). From within Sage, type hg_sage.log() to see the revision history. Note that if you clone an old version, all of the Cython code is rebuilt, since there is no easy way to know which files do and don’t need rebuilding.)
Once you’ve copied the library to a new branch myver and edited some files there, you should build the Sage library to incorporate those changes: type sage -b myver, or just sage -b if the branch myver is already the current branch: that is, if SAGE_ROOT/devel/sage links to SAGE_ROOT/devel/sage-myver. You can also type sage -br myver to build the library and then to immediately run Sage.
If you want to submit your changes to the Sage development team for refereeing (and inclusion into Sage if the referee’s report is positive), you should produce patch files. To do this:
Note that you can also start a very nice web server that allows you to navigate your repository with a web browser, or pull patches from it remotely, by typing hg_sage.serve(). Then open your web browser and point it to http://localhost:8000 which is the default listening address for Mecurial.
Finally, if you want to apply a patch file (perhaps you’ve downloaded a patch from the Trac server for review), use the command hg_sage.patch('filename') (or hg_sage.apply('filename') for hg bundle files).
Sage includes these Mercurial repositories:
The previous section discussed using Mercurial with the Sage library, via the command hg_sage. There are corresponding commands for each of the repositories:
Since version 3.4, both the Sage library and documentation repositories are managed by the command hg_sage.