Developer’s Guide


If you are new to Diofant, start with the Tutorial. If you are willing to contribute - it’s assumed you know the Python programming language and the Git Version Control System.

Guidelines for Contributing

This project adheres to No Code of Conduct. Contributions will be judged by their technical merit. Nothing else matters.

Reporting Issues

When opening a new issue, please take the following steps:

  1. Please search GitHub issues to avoid duplicate reports.
  2. If possible, try updating to master and reproducing your issue.
  3. Try to include a minimal reproducible test case as an example.
  4. Include any relevant details of your local setup (i.e. Python version, installed libraries).

Contributing Code

All work should be submitted via Pull Requests (PR).

  1. PR can be submitted as soon as there is code worth discussing.

  2. Please put your work on the branch of your fork, not in the master branch. PR should generally be made against master.

  3. One logical change per commit. Make good commit messages: short (<= 78 characters) one-line summary, then newline followed by verbose description of your changes.

  4. Please conform to PEP 8 for code formatting, check code quality with flake8 tool:

    $ python flake8
  5. PR should include tests:

    1. Bugfixes should include regression tests.
    2. All new functionality should be tested, every new line should be covered by tests.
    3. All new public interfaces (methods, functions or classes) should have doctests showing how to use them.
    4. Keep in mind, doctests are not tests. Think of them as examples that happen to be tested.
  6. Usually, it’s good idea to be sure that all existing tests pass and you don’t break anything, so please run:

    $ python test


By submitting a PR, you agree to license your code under the BSD license and LGPL.

Rosetta Stone

The Diofant project is a SymPy‘s fork, so it could be handy to collect here some facts about SymPy and explain historical code conventions.

First, the SymPy project was hosted in SVN repository on the Google Code and our master branch include only commits, that added after moving project on the Github. But it’s not a problem for us - we keep old history on the branch sympy-svn-history. Also, you can see this history as part of master’s, if you clone our repo and simply do this:

$ git fetch origin 'refs/replace/*:refs/replace/*'

Please note, that we have dozens of references to SymPy issues in our codebase. Such reference must be either a direct URL of the issue, or a fully qualified reference in the Github format, like sympy/sympy#123. Unqualified references like #123 or issue 123 — are reserved for Diofant’s issues. Functions for regression tests should be named like test_sympyissue_123 and test_diofantissue_123, respectively.

However, in the old Git history, before commit cbdd072, please expect that #123, issue #123 or issue 123 — are references to the SymPy’s issues. The whole story is a little worse, because before commit 6f68fa1 - such unqualified references assume issues on the Google Code, not Github, unless other clearly stated. SymPy issues from the Google Code were moved to the Github in March 2014 (see sympy/sympy#7235). Transfered issue numbers were shifted by 3099. I.e. issue 123 in the history - does mean issue sympy/sympy#3222 on Github.

Versioning and Release Procedure

We use standard Semantic Versioning MAJOR.MINOR.MAINTENANCE numbering scheme, but adopt PEP 440 for alpha (“aN” suffix), beta (“bN” suffix) and release candidates (“rcN” suffix).

Releasing a new version is done as follows:

  1. Increase __version__ in diofant/

  2. Commit version update:

    $ git commit -am 'Bump version to X.Y.Z'
  3. Merge commit to the master branch.

  4. Tag merge commit and push release tag:

    $ git pull
    $ git tag -s vX.Y.Z
    $ git push origin vX.Y.Z

How to Build Documentation

To make the html documentation, first install the Diofant from sources with docs extra requirement, then enter the project directory and run:

python build_sphinx

Documentation tree will be located in the build/sphinx/html/ directory.