### Navigation

- index
- modules |
- next |
- Developer's Guide v6.4.1 »

# 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 describes how to write programs using Sage, how to modify and extend the core Sage libraries, and how to modify Sage’s documentation. We also discuss how to share your new and modified code with other Sage users around the globe.

It is not necessary to memorize this entire guide to begin working on Sage, but careful reading of different sections now will be well worth the effort in seamless contributions later. There are four main things to be aware of.

- All development takes place on or via the Sage Trac server, including bug reports, fixes, new functionality, and discussions about approaches to particular tickets. If you don’t have an account on it, read about how to acquire a Trac account. This is recommended even if you only want to report bugs or request new functionality, not necessarily to help make changes to Sage.
- Next, if you’ve never worked on software before, you will want to read about the prerequisites to compile from the installation guide. This will allow you to make your changes in the source code work. Pay close attention to any system-specific requirements.
- Once you start writing code for Sage, you will want to carefully read the conventions and guidelines we use. (Looking at newer files and functionality within Sage is another way to get a sense for the the general style, but refer here for details.)
  - There is an entire section on how to modify or add to the various manuals and tutorials, including localizing to other languages.
- Finally, in order to share changes with the Sage community, you will need to learn some basics of the source code revision control process. There are several places to start, depending upon your previous knowledge.
  - Don’t forget to acquire a Trac account.
  - First, you will need to install the ‘git’ revision control software if you don’t already have it.
  - Then you will need to go through a short process to configure git for use with Trac.
  - Assuming you have `git` installed and know the basics of how to use it, the next step is the overview of the Sage development flow in the concise development guide.
    - (More advanced tricks and tips for `git` are linked below.)
  - For those unfamiliar with `git` or revision control, please start by reading about collaborative development with Git-Trac, which provides some easier interface with git and Trac, both for newbies and power users.
  - Alternately, one can do certain amounts of Sage development without having `git` installed, by using Sage’s own internal installation of `git` and the Sage dev scripts. This is mainly intended as a bridge to full use of git once one becomes more comfortable with the system.

No matter where you start, good luck and welcome to Sage development!

## Git and Trac

### 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 the Sage Source Code
  - Branching Out
  - The History
  - Editing the Source Code
  - Rebuilding Sage
  - Commits (Snapshots)

### Sage Trac and tickets

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

- The Sage Trac Server
  - Authentication
    - Obtaining an Account
    - Generating and Uploading your SSH Keys
    - Manually Generating your SSH Keys
    - Manually Linking your Public Key to your Trac Account
  - Reporting Bugs
  - Guidelines for Opening Tickets
  - The Ticket Fields
  - Stopgaps
  - Working on Tickets
  - Reviewing Patches
  - Closing Tickets
  - Reasons to Invalidate Tickets

### Git and Trac integration

Putting your local changes on a Trac ticket.

- Collaborative Development with Git-Trac
  - Installing the Git-Trac Command
  - Git and Trac Configuration
  - Trac Tickets to Local Branches
    - Create a Ticket
    - Check out an Existing Ticket
    - Note on Branch Names
  - Uploading Changes to Trac
    - Automatic Push
    - Specifying the Ticket Number
    - Finishing It Up
  - Downloading Changes from Trac
  - Merging
  - Collaboration
    - Exchanging Branches
    - Conflict Resolution
  - Reviewing
- The Sage Dev Scripts
  - Introduction
  - Contributing to the Sage Source Code
    - Create a Ticket
    - Editing the Source Code
    - Uploading Changes to Trac
    - Starting Without a Ticket
  - Merging
  - Reviewing
  - Collaboration

### Git Tricks & Tips

When `git trac` is not enough.

- Git the Hard Way
  - The Trac Server
    - Checking Out Tickets
    - Pushing Your Changes to a Ticket
    - Getting Changes
    - Updating Master
  - Merging and Rebasing
  - Merge Tools
- Tips and References
  - Configuration Tips
    - Aliases
    - Editor
    - Merging
    - Fancy Log Output
  - Tutorials and Summaries
  - Git Best Practices
  - Manual Pages Online
- Advanced Git
  - Detached Heads and Reviewing Tickets
  - Reset and Recovery
  - Rewriting History
  - Interactively Rebasing
- Distributed Development
  - Simple Workflow
  - Public Repository
  - GitHub
    - Fork
    - Develop
    - Push to Trac

## Writing Code for Sage

### Basics of Writing and Testing Sage Code

- General Conventions
  - Python Code Style
  - Files and Directory Structure
  - An Example Is Worth a Thousand Words
  - Headings of Sage Library Code Files
  - Documentation Strings
    - Docstring Markup With ReST and Sphinx
    - LaTeX Typesetting
    - Writing Testable Examples
    - Special Markup to Influence Tests
  - Running Automated Tests
    - Testing .py, .pyx and .sage Files
    - Testing ReST Documentation
  - The Pickle Jar
  - Randomized Testing
  - Global Options
- Doctesting the Sage Library
  - 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 Tests
    - Run Optional Tests
    - Running Tests in Parallel
    - Doctesting All of Sage
    - Debugging Tools
    - Miscellaneous Options

### Contributing to Manuals and Tutorials

- The Sage Manuals
  - Editing the Manuals
  - Hyperlinks
  - Adding a New File
  - Building the Manuals
    - Document Names
    - Output Formats
  - Syntax Highlighting Cython Code

### Sage Coding Details

- Coding in Python for Sage
  - 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
  - Importing
  - Deprecation
  - Using Optional Packages
- Coding in Cython
  - Writing Cython Code in Sage
  - Special Pragmas
  - Attaching or Loading .spyx Files
  - Interrupt and Signal Handling
    - Using `sig_check()`
    - Using `sig_on()` and `sig_off()`
    - Other Signals
    - Error Handling in C Libraries
    - Advanced Functions
    - Testing Interrupts
    - Releasing the Global Interpreter Lock (GIL)
  - 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 Third-Party Code

- Packaging Third-Party Code
  - Directory Structure
    - Install Script
    - Self-Tests
    - Package Versioning
    - The SPKG.txt File
    - Patching Sources
    - Modified Tarballs
    - Checksums
  - Manual package build and installation
  - Inclusion Procedure for New and Updated Packages
    - License Information
    - Prerequisites for New Standard Packages
- Packaging Old-Style SPKGs
  - Creating an Old-Style SPKG
    - Naming Your SPKG
    - Directory Structure
    - The File spkg-install
    - The File SPKG.txt
  - Avoiding Troubles
  - Overview of Patching SPKGs
  - SPKG Versioning

## Sage Notebook Developer Guide

- Sage Notebook Developer Guide
  - Following the Latest Source
    - Get the Local Copy of the Code
    - Updating the Code
  - Making a Patch
    - Making Patches
    - Moving from Patching to Development
  - Git for Development
    - Making Your Own Copy (Fork) of Sage Notebook
    - Set Up Your Fork
    - Development Workflow
    - Maintainer Workflow

## Indices and tables

- Index
- Module Index
- Search Page

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

### Navigation

- index
- modules |
- next |
- Developer's Guide v6.4.1 »