Welcome to the Sage Developer’s Guide!

Warning

Sage development is scheduled to move to GitHub in February 2023. The exact date will be announced in https://groups.google.com/g/sage-devel. After the transition, some parts of this guide (especially those related with the Sage Trac server) will become obsolete and be updated according to the new workflow on GitHub. See our transition guide from Trac to GitHub for the preliminary version of the workflow.

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.

  As an easy way to get started, you can run and edit Sage’s code and contribute your changes using Gitpod, a free online development environment based on VS Code. It will launch a pre-made workspace with all dependencies and tools installed so that you can start contributing straight away. Start by going to Gitpod, and read our Gitpod guidelines to learn more.

• 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.

  • How to install it?

  • How to configure it for use with Trac?

  • Here is an overview of our development flow.

Git and Trac 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)

Using Git with Trac

To contribute back your changes to Sage source code to the project, you will need a ticket on the Sage trac server.

• The Sage Trac Server
  • Obtaining an Account
  • 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
  • The Release Process
• Using Git with the Sage Trac Server
  • Git authentication through SSH
  • The git repository trac.sagemath.org
  • 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
• Optional: Using the Git-Trac Command
  • 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

Writing Code for Sage

• Setting up your workspace
  • Configuring text editors and IDEs for use with Sage
  • Gitpod
• 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
    • Fine points on styles
    • 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 testing on multiple platforms on GitHub Actions
  • Using our pre-built Docker images published on ghcr.io
  • Using our pre-built Docker images for development in VS Code

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
    • Package tags
    • 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

• Search Page

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