Development Walk-through¶

This section is a concise overview of the Sage development process. We will see how to make changes to the Sage source code and record them in the Git revision control system.

Quick start¶

If you are in a hurry, you can skip the details and just follow these steps:

Install Git (see Installing Git) and Conda.

Clone the Sage repository from GitHub:

$ git clone --origin upstream https://github.com/sagemath/sage.git

Change into the directory:
```
$ cd sage
```

Create a new Conda environment:

$ conda env create --file environment-3.12-linux.yml --name sage-dev
$ conda activate sage-dev

Replace ``environment-3.12-linux.yml`` with the appropriate file for your system.

Build and install Sage:

$ pip install --no-build-isolation --editable .

Create a new branch for your changes:
```
$ git checkout -b my_branch develop
```

Make your changes, and push them to your fork on GitHub:

$ git add .
$ git commit -m "Your commit message here"
$ git push origin my_branch

Create a pull request on GitHub to merge your changes into the Sage repository.

Checking Git¶

First, open a shell (for instance, Terminal on Mac) and check that Git works:

$ git --version
git version xyz

If you got a “command not found” error, then you don’t have Git installed; now is the time to install it. See Installing Git for instructions.

Because we also track who does what changes with Git, you must tell Git how you want to be known. Check if Git knows you:

$ git config --global user.name
Alice Adventure
$ git config --global user.email
alice@wonderland.com

If you see your name and email address, then you are all set. This name/email combination ends up in commits. So if it’s not set yet, do it now before you forget! This only needs to be done once. See Configuring Git for instructions.

Obtaining the Sage source code¶

Obviously one needs the Sage source code to develop. You can download it from our Sage repository on GitHub:

$ git clone --origin upstream https://github.com/sagemath/sage.git
Cloning into 'sage'...
$ cd sage

This creates a directory named sage containing the most recent version of the Sage source code.

Building Sage¶

Sage is a large project with many dependencies. To build it, we recommend using Conda. If you don’t have Conda installed, you can install it by following the official instructions:

$ curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
$ bash Miniforge3-$(uname)-$(uname -m).sh

Now create and activate a new conda environment with the dependencies of Sage and a few additional developer tools:

$ conda env create --file environment-3.12-linux.yml --name sage-dev
$ conda activate sage-dev

Replace environment-3.12-linux.yml with the appropriate file for your system. You can find the environment files in the root directory of the Sage repository.

Now you can build and install Sage::

$ pip install --no-build-isolation --editable .

This will install Sage in the current Conda environment. You can then start Sage from the command line with sage.

For more information on building Sage we refer to the section building from source in the Sage installation guide.

Branching out¶

In order to start modifying Sage, we want to make a new branch in the local Sage repo. A branch is a copy (except that it doesn’t take up twice the space) of the Sage source code where you can store your modifications to the Sage source code (and which you can push to your fork of the Sage repository on GitHub).

To begin with, type the command git branch. You will see the following:

$ git branch
* develop
  master

The asterisk shows you which branch you are on. Without an argument, the git branch command displays a list of all local branches with the current one marked by an asterisk.

It is easy to create a new branch, as follows:

$ git checkout -b last_twin_prime develop

This will create a new branch named last_twin_prime based on the develop branch and switch to it.

Now if you use the command git branch, you will see the following:

$ git branch
  develop
* last_twin_prime
  master

Note that unless you explicitly push a branch to a remote Git repository, the branch is a local branch that is only on your computer and not visible to anyone else.

Editing the source code¶

Once you have your own branch, feel free to make any changes to source files as you like. The chapter Writing Code for Sage explains how your code should look like to fit into Sage, and how we ensure high code quality throughout.

The Git command git status is probably the most important of all Git commands. It tells you which files changed, and how to continue with recording the changes:

$ git status
On branch last_twin_prime
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

    modified:   some_file.py
    modified:   src/sage/primes/all.py

Untracked files:
  (use "git add <file>..." to include in what will be committed)

    src/sage/primes/last_pair.py

no changes added to commit (use "git add" and/or "git commit -a")

To dig deeper into what was changed in the files you can use:

$ git diff some_file.py

to show you the differences.

Testing changes¶

Once you have made any changes, you of course want to try out your edits. All changes to Python and Cython files take effect immediately after restarting Sage, so there is no need to explicitly rebuild Sage.

The changes can be tested by running Sage and verifying that the modifications work as expected. For example, if you modified a function, you can call it directly in Sage to ensure it behaves as intended.

Additionally, you can write or modify doctests in the relevant files to confirm the correctness of your changes. To run the doctests for a specific file, use the following command:

$ ./sage -t path/to/your/file.py

This will execute all the doctests in the specified file and report any failures. Make sure all tests pass before proceeding (see Running Sage’s Doctests for more details). Also, don’t forget to build the documentation (see The Sage Manuals).

Making commits¶

Whenever you have reached your goal, a milestone towards it, or just feel like you got some work done you should commit your changes. A commit is just a snapshot of the state of all files in the repository.

You first need to stage the changed files, which tells Git which files you want to be part of the next commit:

$ git status
On branch last_twin_prime
Untracked files:
  (use "git add <file>..." to include in what will be committed)
      src/sage/primes/last_pair.py
nothing added to commit but untracked files present (use "git add" to track)

$ git add src/sage/primes/last_pair.py
$ git status
On branch last_twin_prime
Changes to be committed:
  (use "git reset HEAD <file>..." to unstage)
  new file:   src/sage/primes/last_pair.py

Once you are satisfied with the list of staged files, you create a new snapshot with the git commit command:

$ git commit
... editor opens ...
[last_twin_prime 31331f7] Added the very important foobar text file
 1 file changed, 1 insertion(+)
  create mode 100644 foobar.txt

This will open an editor for you to write your commit message. The commit message should generally have a one-line description, followed by an empty line, followed by further explanatory text:

Added the last twin prime

This is an example commit message. You see there is a one-line
summary followed by more detailed description, if necessary.

You can then continue working towards your next milestone, make another commit, repeat until finished. As long as you do not git checkout another branch, all commits that you make will be part of the branch that you created.

Open pull request¶

Once you are happy with your changes, you can propose these for review and integration into the main project. The first step is to push your branch to your fork of the the Sage repository on GitHub. This is done with the command:

$ git push origin last_twin_prime

Now you can go to GitHub and create a pull request. See Using Git with GitHub for more details on the workflow of creating a pull request and the review process.