Introduction to contributing

Jason K. Moore edited this page Oct 4, 2016 · 9 revisions
Clone this wiki locally

SymPy is created and maintained by a large group of contributors and we'd love you to be one too! Getting started in a well-oiled large and complex machine like SymPy can be daunting for new contributors. This page exists to give tips for new contributors to get started.

Get familiar using the software

We suggest going through the SymPy Tutorial to get acquainted with using the software before you begin contributing. This will help you familiarize yourself with the uses for SymPy.

The tutorial is also available on video:

Peruse the documentation

Beside the tutorial, there is a lot more information in the documentation. It's probably a good idea to at least browse through the different topics to get an idea of what else is available. For example, the architecture section gives an overview of how the SymPy code is organized and is useful for a contributor to know about.

Setup your development environment

We use the Git version control system to track the software changes over time and to effectively manage contributions from many different authors. We also utilize Github, a web interface to Git, extensively and use it for communication, issue tracking, merging patches (i.e. Pull Requests), etc.

You will need to read through the Development Workflow page and follow the instructions to setup your development environment before making a contribution. It is easiest for us if you make use of Github's "Pull Request" system for sending in patches and code contributions.

Join our mailing list

The SymPy email mailing list is one place where discussions about SymPy happen. You can ask questions about how to use SymPy, discuss feature requests, discuss software bugs, or share how you are using SymPy. Request to join the list on the Google Groups page.

Join the Gitter chat room

We have a live chat room where we discuss things about SymPy at Gitter: https://gitter.im/sympy/sympy. Here you may find other SymPy developer's and you can ask questions in real time.

Peruse the Wiki

Another good source of information is the SymPy Wiki. It's a good idea to browse through the topics there. And feel free to create or edit a page. For example, you can create a page to plan out code modifications you have in mind.

Identify something to work on

There are lots of ways to contribute to SymPy. Most contributions center around fixing software bugs and adding new features. But there are other things we need help with to, like maintaining our websites, writing documentation, preparing tutorials, answering people's questions on the mailing lists, chat room, and issue tracker. Here are some following ways to get started with a contribution:

SymPy Codebase

The best way to start with the main code base is to fix some existing bugs. Peruse the "Easy to fix" issues in the issue tracker and see if one interests you. If you'd like to try to fix it, then create a message in the issue saying that you'd like to work on it. If it isn't clear how to fix it, ask for suggestions on how to do it in the issue itself, on the mailing list, or on Gitter.

SymPy's code is organized into Python packages and modules. The core code is in the sympy/core directory and other packages in the sympy directory have more specific code, for example sympy/printing handles how SymPy objects are printed to the terminal, in IPython notebooks, or in our web applications.

Project Ideas Page

If you are looking for a somewhat larger project to implement, check out the Project General Ideas page. This page is a collection of projects that contributors have come up with but have not yet had the time or opportunity to implement themselves.

Documentation

If you'd like to improve the documentation you can edit in one of two places:

  1. The documentation source files: https://github.com/sympy/sympy/tree/master/doc/src
  2. The docstrings* of the functions in the source code: https://github.com/sympy/sympy/tree/master/sympy

Both of these end up displayed on the documentation website:

  1. Example rendered prose: http://docs.sympy.org/latest/guide.html and it's corresponding source: https://github.com/sympy/sympy/blob/master/doc/src/guide.rst
  2. Example rendered docstrings: http://docs.sympy.org/latest/modules/core.html and the corresponding source: https://github.com/sympy/sympy/blob/master/sympy/core/sympify.py#L55

* Every function and class in SymPy has a string below call signature explaining the use of the object. This is what is displayed in Python when you type help(function_name).

SymPy Websites

We have three websites: sympy.org, live.sympy.org, sympygamma.com. The first is our primary web presence and is a "static" website. The last two are interactive web applications where you can use SymPy without installing it and they run on servers provided by the Google App Engine.

  1. Edit the files for the main SymPy website: https://github.com/sympy/sympy.github.com and check out the issue tracker for the website: https://github.com/sympy/sympy.github.com/issues.
  2. Both SymPy Live and SymPy Gamma have their own repositories: https://github.com/sympy/sympy-live https://github.com/sympy/sympy_gamma and issue trackers. If you'd like to contribute to those websites, start there.

Review pull requests

Every repository has a "Pull Request" section where people send the code they'd like to contribute to SymPy. For example, https://github.com/sympy/sympy/pulls. You can view the code submission and check whether it does what it is intended to do. Every pull request has to be reviewed and approved by a reviewer before we merge it into the main code base.