Welcome to Sage Developer Guide

Note

Sage development moved to GitHub in February 2023, from the Sage Trac server, which had been the center of Sage development for a long time. After the transition, this guide was updated accordingly. However, the legacy is still with us in many aspects of the current Sage development.

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 or create a new class

• Contribute a useful tutorial for a mathematical topic

• Translate an existing document to a new language

• Upgrade a package, create a fast new C library, etc.

This document tells you what you need to know to do all the above. We also discuss how to share your new and modified code with other Sage users around the globe.

To begin with, you need of course your own copy of Sage source code to change it. Use our Installation guide to get the source code and build Sage from source. If you have never worked on software before, pay close attention to the prerequisites to build on your platform.

Now here is a brief overview of this guide.

• First Steps: To share changes with the Sage community, you need to learn about revision control. We use the software Git for this purpose. Here we walk you through from setting up Git on your platform and to preparing a local branch to share with all Sage users.

  Note

  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.

• Working on GitHub: All changes go through the Sage repository on GitHub at some point. It contains bug reports, enhancement proposals, changes in progress, and indeed all the history of Sage today. You have to be familiar with it to be involved in Sage development.

• Working with Git: Here we give an in-depth guide for working with Git for Sage development. Read this when you need help on Git in a tricky situation such as merge conflict.

• Writing Code for Sage: This is a guide on conventions in writing code and documentation. A beginning developer should read this to be a good developer. As conventions evolve over time, also experienced Sage contributors may want to review this chapter once in a while.

• Testing Sage: We value testing Sage highest. Every change of Sage source code has a risk to break Sage, and must be tested before being merged. This part explains our various tools to help test Sage.

• Updating Sage Documentation: All features of Sage are documented in our manuals. This part explains the technical aspect of updating Sage documentation.

• More on Coding for Sage: When you need to know the technical details of Sage for deep coding, read this.

• Packaging: Sage is composed of many third-party packages and its own distribution packages. This part is for advanced developers.

For more details, see the table of contents below. No matter where you start, good luck and welcome to Sage development!

Table of Contents

First Steps

• Development Walk-through
  • Checking Git
  • Obtaining the Sage source code
  • Branching out
  • The history
  • Editing the source code
  • Rebuilding Sage
  • Making commits
• Setting Up Git
  • Installing Git
  • Configuring Git

Working on GitHub

• The Sage Repository on GitHub
  • Obtaining a GitHub account
  • Using the GitHub CLI
  • Linking Git to your GitHub account
  • Forking the Sage repository
  • Reporting bugs
  • Planning an enhancement
  • Opening an issue
  • Creating a Pull Request
  • The status of a PR
  • The stopgap
  • Commenting issues and PRs
  • Checks on PRs
  • Final notes
• Using Git with GitHub
  • Development workflow at a glance
  • Creating a new PR
  • Checking out an existing PR
  • Uploading more changes to GitHub
  • Finishing it up
  • Merging the upstream develop branch
• Reviewing Code
  • Reviewing and closing PRs
  • Reasons to invalidate PRs
  • The release process

Working with Git

• Git Basics
  • Git authentication through SSH
  • Pushing your changes to a remote
  • Checking out a PR
  • Getting changes from a remote
  • Updating develop
  • Merging and rebasing
  • Merge tools
• Advanced Git
  • Detached heads and reviewing PRs
  • Update branch to latest Sage version
  • Reset and recovery
  • Rewriting history
  • Interactively rebasing
• Git Tips and References
  • Configuration tips
  • Tutorials and summaries
  • Git best practices
  • Manual pages online

Writing Code for Sage

• Setting up Your Workspace
  • 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
  • Running automated doctests
  • General coding style regarding whitespace
  • Global options
  • Miscellaneous minor things

Testing Sage

• 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
  • The doctest fixer
• Testing on Multiple Platforms
  • Testing PRs with GitHub Actions
  • Sage buildbots
  • Test reports on sage-release
  • Testing on multiple platforms using Docker
  • 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
• Development and Testing Tools
  • Tox
  • Doctest
  • Doctest with Coverage.py
  • Coverage
  • Startuptime
  • Pycodestyle
  • Cython-lint
  • Ruff
  • Relint
  • Codespell
  • Pytest
  • Pyright
  • Pyflakes
  • Act

Updating Sage Documentation

• The Sage Manuals
  • Editing the documentation
  • Hyperlinks
  • Adding a new file
  • Making portions of the reference manual conditional on optional features
  • Building the manuals
  • Syntax highlighting Cython code

More on Coding for Sage

• 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
  • Static typing
  • Deprecation
  • Using optional packages
• Coding in Cython
  • Writing cython code in Sage
  • Attaching or loading .spyx files
  • Interrupt and signal handling
  • Unpickling Cython code
  • Deprecation
• Using External Libraries and Interfaces
  • The PARI C library interface
  • GAP
  • LibGAP
  • Singular
  • Singular: another approach
  • Creating a new pseudo-TTY interface

Packaging

• Packaging Third-Party Code for Sage
  • Package types
  • Directory structure
  • Utility script to create and maintain packages
  • Building the package
  • Modifying third-party code
  • Inclusion procedure for new and updated packages
• Packaging the Sage Library for Distribution
  • Modules, packages, distribution packages
  • Source directories of distribution packages
  • Dependencies and distribution packages
  • Hierarchy of distribution packages
  • Testing distribution packages

Indices and tables

• Index

• Search Page

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