Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Introduction to contributing
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:
- Symbolic Computation with Python using SymPy | SciPy 2016
- SymPy Tutorial SciPy 2014 Part 1 Part 2 Part 3
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.
Join our mailing list and introduce yourself
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. Please read http://shakthimaan.com/downloads/book/chapter1.pdf before posting to get familiar with mailing list etiquette.
To introduce yourself please send us an informative first email so that we can get to know you. Here are some example pieces of information that would be useful for you to include in your introductory email:
- level of familiarity with python (years of programming, previous projects)
- mathematical education level (high school / ... / PhD?)
- particular expertise (physics? biology? ...subtopics)
- particular algorithmic interests
- level of familiarity with symbolic math systems "computer algebra". Perhaps even course work in (say) algebra, or books read.
- your familiarity with SymPy (e.g. how have you used SymPy)?
- other possibly relevant information -- geographical location? native language?
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 developers 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.
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.
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:
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. Another good place to look for ideas are the Google Summer of Code ideas pages: GSoC 2018 Ideas, GSoC 2017 Ideas, GSoC 2016 Ideas, ...
If you'd like to improve the documentation you can edit in one of two places:
- The documentation source files: https://github.com/sympy/sympy/tree/master/doc/src
- 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:
- 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
- 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
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.
- 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.
- 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. The blgopost "Mindful Communications in Code Reviews" is helpful to read before reviewing for SymPy.