Skip to content

Latest commit

 

History

History
195 lines (131 loc) · 5.06 KB

index.rst

File metadata and controls

195 lines (131 loc) · 5.06 KB
Raw

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.

  • section-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 <section-gitpod> to learn more.

  • section-development-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.
  • section-git-tricks-and-tips: 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.
  • section-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.
  • section-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.
  • section-updating-documentation: All features of Sage are documented in our manuals. This part explains the technical aspect of updating Sage documentation.
  • section-more-on-coding: When you need to know the technical details of Sage for deep coding, read this.
  • section-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

walkthrough git_setup

Working on GitHub

github workflows review

Working with Git

git_basic git_advanced git_background

Writing Code for Sage

workspace coding_basics

Testing Sage

doctesting portability_testing tools

Updating Sage Documentation

sage_manuals

More on Coding for Sage

coding_in_python coding_in_cython coding_in_other

Packaging

packaging packaging_sage_library

Indices and tables

  • genindex
  • search

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