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.
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.
Git for Sage development¶
First Steps with Git¶
Sage uses git for version control.
The git-trac command¶
Putting your local changes on a Trac ticket.
Git Tricks & Tips¶
git trac is not enough.
- Git the Hard Way
- Tips and References
- Advanced Git
- Distributed Development
Sage Trac and tickets¶
All changes to Sage source code require a ticket on the Sage trac server.
Writing Code for Sage¶
- Setting up your workspace
- 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
- The reviewer’s check list
Running Sage’s tests¶
- Running Sage’s doctests
- Testing a Module
- Parallel Testing Many Modules
- Parallel Testing the Whole Sage Library
- Beyond the Sage Library
- Doctesting from Within Sage
- Optional Arguments
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¶
Contributing to Manuals and Tutorials¶
Sage Coding Details¶
- Coding in Python for Sage
- Python Language Standard
- Special Sage Functions
- Sage Preparsing
- The Sage Coercion Model
- The __hash__ Special Method
- Integer Return Values
- Using Optional Packages
- Coding in Cython
- Using External Libraries and Interfaces
Packaging the Sage Library¶
- Packaging the Sage Library
- Modules, packages, distribution packages
- Source directories of distribution packages
- Dependencies and distribution packages
- Hierarchy of distribution packages
- Testing distribution packages
Packaging Third-Party Code¶
- Packaging Third-Party Code
- Package 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
- 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
Indices and tables¶
This work is licensed under a Creative Commons Attribution-Share Alike 3.0 License.