# 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 worksheet

If you would like to share a worksheet for the examples or gallery pages, please sent it (preferably in Jupyter notebook 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.
Tickets ready for review are those whose number is displayed in
orange on
the Trac page
(the green ones are tickets which got
a positive review, and the ~~barred green~~
ones are tickets already integrated in SageMath).

Please follow the reviewer guidelines. You may also find more information on SageMath Trac development server here.

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

## Writing code

### 1. Starting from the latest sources

Given the open-source nature of SageMath, it is quite easy to improve some
parts of SageManifolds or to implement new functionalities. For this, you need
to edit the Python source code. 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 (8.0 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 tickets
merged in the development version of SageMath
(the so-called *beta* versions, for instance 8.1.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 list of required packages for Ubuntu. Then 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/sagemath/sage.git`

(downloads
stable SageMath sources in a new directory (`sage`

))

`cd sage`

(this directory will be your new `SAGE_ROOT`

)

`git checkout -b develop`

(creates a new git branch, named `develop`

, and makes it the current branch)

`git pull origin develop`

(downloads the
latest development sources)

`MAKE="make -j8" make`

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

For more details, see the
git section
of Sage's Developer Guide.

### 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.
Above all, please write Python3-compatible code, since the migration of SageMath to Python3 is close!

To rebuild SageMath after your changes, type (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, you shall push them to the SageMath Trac development server and open an associated ticket. If you don't have any account on the Trac server yet, follow these instructions to get one. Then, link your ssh public key to your trac account according to these instructions (if you don't have a ssh public key yet, see here to generate one).

Before pushing your changes to the Trac server, you have to add the latter to your list of remote git repositories by

git remote add trac git://trac.sagemath.org/sage.git -t master git remote set-url --push trac git@trac.sagemath.org:sage.gitThen commit your changes:

git commit -a -m "Short description of your changes"and push them to a new branch of the Trac server, e.g.

`public/manifolds/topic`

, replacing `topic`

by the
actual topic of your work:
git push trac HEAD:public/manifolds/topic

*Remarks:* (i) if the branch `public/manifolds/topic`

did not exist
previously on the Trac server (this should be the case if this is your first push),
it is created by the above command; (ii) no
explicit password is required because the push uses the
authentication provided by your public ssh key, as discussed above.

Having pushed your code to a new branch of the git repository on SageMath Trac, there remains to open a ticket, in order to submit your work for integration in SageMath. To this aim, log in at trac.sagemath.org, click on the "New Ticket" button in the upper right and fill the various fields as follows:

**Type**:*defect*if you are fixing some bug or*enhancement*if you are providing some new functionality**Keywords**: mathematical keywords corresponding to your changes**Component**: usually*geometry***CC**: usernames of people whom you want to let know about your ticket**Authors**: your full name (not your username)**Branch**: name of the git branch that you have pushed to the Trac server, i.e.`public/manifolds/topic`

(replacing of course`topic`

by the actual topic of your ticket)**Dependencies**: number of a ticket (not integrated in SageMath yet) on which your ticket may depend on.

You may leave the other fields to blank or to their default values; see the guidelines for opening tickets for more details.

After your ticket is created, add it to the list of manifold tickets by clicking on the button "Modify" in the upper right of the SageManifolds metaticket. In addition, you may consider sending a message to the mailing list to let other people know about your ticket and possibly review it. That's it! Thank you for contributing to the project!