# Contribute

In the open source spirit, everybody is welcome to take part in the SageManifolds project. There are actually various ways to contribute:## Sharing a notebook

If you would like to share a notebook for the examples or gallery pages, please send it (in Jupyter format) to this address.

## Reviewing SageManifolds code

If you know about Python (*), please consider reviewing SageManifolds code under development for the next version of SageMath. Such a code is available as opened pull requests listed at this GitHub page (**). Please follow the reviewer guidelines.

(*) Even if you are not a Python guru, you can significantly contribute to a pull request review by checking the mathematical correctness and documentation quality of the proposed changes.

(**) Before February 2023, the SageMath development infrastructure was based on a Trac server; since then, it has been migrated to GitHub.

## Writing code

Given the open-source nature of SageMath, it is quite easy to improve some parts of SageManifolds or to implement new functionalities. You may first have a look at these lecture notes, which describe some details of the implementation.### 1. Starting from the latest sources

To write some code, you need to edit the Python source files. In the root directory of your SageMath install,
hereafter called `SAGE_ROOT`

(you can locate this directory by typing `sage -root`

in a terminal
or `!sage -root`

in some cell of a Jupyter notebook),
the SageManifolds code lies in two subdirectories:

`SAGE_ROOT/src/sage/tensor/modules/`

for the pure algebraic part (tensors on free modules)`SAGE_ROOT/src/sage/manifolds/`

for the topological and differential parts

Before starting to modify the sources, make sure that you are dealing with the
latest stable version of SageMath (10.1 at the moment). Even better, you could
work on the latest *development* version of SageMath.
This is even necessary if the planned changes depend upon previous SageManifolds code
merged in the development version of SageMath
(the so-called *beta* versions, for instance 10.2.beta0).

To download and install the development version of SageMath, proceed as follows. First of all, make sure the prerequisites needed to build
SageMath from sources are installed on your computer: check this
page
or this page for Ubuntu/Debian.
Then, create a (free) account at github.com,
if you don't have any yet, and fork the repository `sagemath/sage`

under
`USERNAME/sage`

, where `USERNAME`

is your GitHub account name.
Next type the following commands in a terminal from,
let us say, your home directory (*not* the root directory of your current
stable SageMath install):

`git clone https://github.com/USERNAME/sage.git`

(download
SageMath sources into a new directory, named `sage`

)

`cd sage`

(this directory will be the `SAGE_ROOT`

directory)

`git remote add upstream https://github.com/sagemath/sage.git`

`make configure`

`./configure`

`MAKE="make -j8" make`

(compile SageMath on 8 threads; adapt to your CPU)

### 2. Coding your changes

Whatever method you choose (i.e. working in the `src`

subdirectory of either your stable SageMath install or the development version), it is recommended to create
a new git branch to store your changes, in order to revert easily to the original
version:

`git checkout -b my_changes`

(creates the git branch `my_changes`

and makes it the current branch)

Then edit or add some source files in `SAGE_ROOT/src/sage/manifolds/`

(or `SAGE_ROOT/src/sage/tensor/modules/`

for pure algebraic stuff). It is mandatory to follow
the programming rules exposed in the Sage Developerâ€™s Guide; in particular read carefully the section
Writing Code for Sage.

If your changes regard other files than Python ones (e.g. Cython source files), you need
to rebuild SageMath by typing (from the `SAGE_ROOT`

directory):

./sage -b

### 3. Running doctests

Doctests are testable examples that are embedded in docstrings of Python classes and functions
(more generally in comments part of Python source files). They are automatically tested via the command `sage -t`

. So after your changes, you should run

./sage -t --long src/sage/manifolds/

Note that `-t`

can be replaced by `-tp`

to run doctests in parallel
(cf. `./sage -t --help`

for the full list of options controlling doctest runs).
You should also check that all the new functions that you have introduced have
doctests:

./sage -coverage src/sage/manifolds/

### 4. Generating and checking the documentation

Please take time to document your changes as much as possible, especially by providing
examples of use in the docstrings following these
rules. If you have added new source files, you may have to edit some `rst`

files
in `SAGE_ROOT/src/doc/en/reference/manifolds/`

,
so that the new files are taken into account in the documentation. Note that
bibliographic references shall be put in the master file
`SAGE_ROOT/src/doc/en/reference/references/index.rst`

.
To generate the documentation from the docstrings in Python source files, run
(from the `SAGE_ROOT`

directory)

./sage -docbuild reference/manifolds html

(if you get an error, you may need to regenerate the whole reference manual
by `make doc-clean && make doc`

). The generated documentation lies in

SAGE_ROOT/local/share/doc/sage/html/en/reference/manifolds/index.html

This is actually the manifolds section of the whole SageMath reference manual,
which is at `SAGE_ROOT/local/share/doc/sage/html/en/reference/index.html`

.

### 5. Sharing your changes

When you are ready to share your changes, create a new commit on your local git branch `my_changes`

:

git commit -a -m "Short description of your changes"Then push the branch to your fork

`USERNAME/sage`

on GitHub (i.e. to the remote labelled `origin`

):
git push --set-upstream origin my_changesThis will create the new branch

`my_changes`

in the GitHub repository `USERNAME/sage`

and will set it to the be the upstream of the local branch `my_changes`

(thanks to the
`--set-upstream`

option).
In the returned message on your terminal, you will get some url link for opening a pull request on
the develop branch of `sagemath/sage`

. When filling the pull request form, please select
`c: manifolds`

and `s: needs review`

in the *Labels*menu (

`c:`

stands for *component*and

`s:`

for *status*). If the reviewer is asking for some modifications and you implement them in the local branch

`my_changes`

, it will suffice to run
git pushto push the modifications to the remote branch

`my_changes`

of `USERNAME/sage`

(no need to specify `--set-upstream`

).
For more details, see this page and take a look at the video about the new development workflow.

That's it! Thank you for contributing to the project!