Welcome to the Sage Developer’s Guide!

Everybody who uses Sage is encouraged to contribute something back to Sage at some point. You could:

• Add examples to the documentation

• Find bugs or typos

• Fix a bug

• Implement a new function

• Contribute a useful tutorial for a mathematical topic

• Translate an existing document to a new language

• Create a new class, create a fast new C library, etc.

This document tells you what you need to know to do all the above, from reporting bugs to modifying and extending Sage and its documentation. We also discuss how to share your new and modified code with other Sage users around the globe.

Here are brief overviews of each part; for more details, see the extended table of contents below. No matter where you start, good luck and welcome to Sage development!

• Trac server: all changes go through the Sage Trac server at some point. It contains bug reports, upgrade requests, changes in progress, and those already part of Sage today. Click here for more information.

  Importantly, you will need to create a trac account in order to contribute.

• Source code: You need your own copy of Sage’s source code to change it. Go there to get it and for instructions to build it.

  If you have never worked on software before, pay close attention to the prerequisites to compile on your system.

• Conventions: read our conventions and guidelines for code and documentation.

  For everything related to manuals, tutorials, and languages, click here.

• Git (revision control): To share changes with the Sage community, you will need to learn about revision control; we use the software Git for this purpose.

  • Here is an overview of our development flow.

  • Unfamiliar with Git or revision control?

  • How to install it?

  • How to configure it for use with Trac?

Git for Sage development

First Steps with Git

Sage uses git for version control.

• Setting Up Git
  • Installing Git
  • Your Name and Email
• Sage Development Process
  • Configuring Git
  • Obtaining and Compiling the Sage Source Code
  • Branching Out
  • The History
  • Editing the Source Code
  • Rebuilding Sage
  • Commits (Snapshots)

The git-trac command

Putting your local changes on a Trac ticket.

• Collaborative Development with Git-Trac
  • Installing the Git-Trac Command
  • Git and Trac Configuration
  • Trac Tickets and Git Branches
  • Uploading Changes to Trac
  • Downloading Changes from Trac
  • Merging
  • Collaboration and conflict resolution
  • Reviewing

Git Tricks & Tips

When git trac is not enough.

• Git the Hard Way
  • The Trac Server
  • Merging and Rebasing
  • Merge Tools
• Tips and References
  • Configuration Tips
  • Tutorials and Summaries
  • Git Best Practices
  • Manual Pages Online
• Advanced Git
  • Detached Heads and Reviewing Tickets
  • Update Branch to Latest SageMath Version (and Minimizing Recompilation Time)
  • Reset and Recovery
  • Rewriting History
  • Interactively Rebasing
• Distributed Development
  • Simple Workflow
  • Public Repository
  • GitHub

Sage Trac and tickets

All changes to Sage source code require a ticket on the Sage trac server.

• The Sage Trac Server
  • Obtaining an Account
  • Trac authentication through SSH
  • Reporting Bugs
  • Guidelines for Opening Tickets
  • The Ticket Fields
  • The status of a ticket
  • Stopgaps
  • Working on Tickets
  • Reviewing and closing Tickets
  • Reasons to Invalidate Tickets

Writing Code for Sage

• General Conventions
  • Python Code Style
  • Files and Directory Structure
  • Learn by copy/paste
  • Headings of Sage Library Code Files
  • Documentation Strings
    • The docstring of a function: content
    • LaTeX Typesetting
    • Writing Testable Examples
    • Special Markup to Influence Doctests
  • Running Automated Doctests
    • Testing .py, .pyx and .sage Files
    • Testing reST Documentation
  • General Coding Style Regarding Whitespace
  • Global Options
  • Miscellaneous minor things
• The reviewer’s check list

Running Sage’s tests

• Running Sage’s doctests
  • Testing a Module
  • Troubleshooting
  • Parallel Testing Many Modules
  • Parallel Testing the Whole Sage Library
  • Beyond the Sage Library
  • Doctesting from Within Sage
  • Optional Arguments
    • Run Long Doctests
    • Run Optional Doctests
    • Running Doctests in Parallel
    • Doctesting All of Sage
    • Debugging Tools
    • Miscellaneous Options

Testing on multiple platforms

• Testing on multiple platforms
  • Sage patchbots
  • Sage buildbots
  • Developers’ and users’ tests on sage-release
  • Testing Sage on a different platform using Docker
    • Discovering the system’s package system
    • Using Sage’s database of distribution prerequisites
    • Using Sage’s database of equivalent distribution packages
    • Committing a container to disk
    • Generating Dockerfiles
    • Debugging a portability bug using Docker
    • Automatic Docker-based build testing using tox
    • Automatic build testing on the host OS using tox -e local-direct
    • Automatic build testing on the host OS with best-effort isolation using tox -e local
    • Automatic build testing on macOS with a best-effort isolated installation of Homebrew
    • Automatic build testing with a best-effort isolated installation of Conda
    • Options for build testing with the local technology
    • Automatic parallel tox runs on GitHub Actions

Additional development and testing tools

• Additional development and testing tools
  • Tox
  • Doctest
  • Coverage
  • Startuptime
  • Pycodestyle
  • Relint
  • Codespell
  • Pytest
  • Pyright
  • Pyflakes

Contributing to Manuals and Tutorials

• The Sage Manuals
  • Editing the documentation
  • Hyperlinks
  • Adding a New File
  • Building the Manuals
    • Document Names
  • Syntax Highlighting Cython Code

Sage Coding Details

• Coding in Python for Sage
  • Python Language Standard
  • Design
  • Special Sage Functions
    • LaTeX Representation
    • Print Representation
    • Matrix or Vector from Object
  • Sage Preparsing
  • The Sage Coercion Model
  • Mutability
  • The __hash__ Special Method
  • Exceptions
  • Integer Return Values
  • Importing
  • Deprecation
    • Experimental/Unstable Code
  • Using Optional Packages
• Coding in Cython
  • Writing Cython Code in Sage
  • Attaching or Loading .spyx Files
  • Interrupt and Signal Handling
  • Unpickling Cython Code
• Using External Libraries and Interfaces
  • The PARI C Library Interface
  • GAP
  • LibGAP
  • Singular
  • Singular: Another Approach
  • Creating a New Pseudo-TTY Interface

Packaging the Sage Library

• Packaging the Sage Library
  • Modules, packages, distribution packages
    • Ordinary packages vs. implicit namespace packages
  • Source directories of distribution packages
  • Dependencies and distribution packages
    • Build-time dependencies
    • Module-level runtime dependencies
    • Other runtime dependencies
    • Doctest-only dependencies
    • Version constraints of dependencies
  • Hierarchy of distribution packages
  • Testing distribution packages
    • Preparing doctests
    • Testing the distribution in virtual environments with tox

Packaging Third-Party Code

• Packaging Third-Party Code
  • Package types
    • Package source types
  • Directory Structure
    • Package type
    • Build and install scripts of normal packages
    • Install scripts of script packages
    • Helper functions
    • Allowing for the use of system packages
    • Self-Tests
    • Python-based packages
    • The SPKG.rst File
    • Package dependencies
    • Where packages are installed
    • Patching Sources
    • When to patch, when to repackage, when to autoconfiscate
    • How to maintain a set of patches
    • Modified Tarballs
    • Package Versioning
    • Checksums and Tarball Names
    • Upstream URLs
  • Utility script to create packages
  • Building the package
  • Inclusion Procedure for New and Updated Packages
    • License Information
    • Prerequisites for New Standard Packages

Indices and tables

• Index

• Module Index

• Search Page

This work is licensed under a Creative Commons Attribution-Share Alike 3.0 License.