Development
Warning
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.
This project adheres to No Code of Conduct. Contributions will be judged by their technical merit.
Reporting Issues
When opening a new issue, please take the following steps:
Please search GitHub issues to avoid duplicate reports.
If possible, try updating to master and reproducing your issue.
Try to include a minimal code example that demonstrates the problem.
Include any relevant details of your local setup (Diofant version, Python version, installed libraries).
Note
Please avoid changing your messages on the GitHub, unless you want fix a typo and so on. Just expand your comment or add a new one.
Contributing Code
All work should be submitted via Pull Requests (PR).
PR can be submitted as soon as there is code worth discussing. Please make a draft PR, if one is not intended to be merged in its present shape even if all checks pass.
Please put your work on the branch of your fork, not in the master branch. PR should generally be made against master.
One logical change per commit. Make good commit messages: short (<= 78 characters) one-line summary, then newline followed by verbose description of your changes. Please mention closed issues with commit message.
Please conform to PEP 8 and PEP 257; run:
flake518
to check formatting.
PR should include tests:
Bugfixes should include regression tests (named as
test_issue_123
for Diofant issues and astest_sympyissue_123
for SymPy issues).All new functionality should be tested, every new line should be covered by tests. Please use in tests only public interfaces. Regression tests are not accounted in the coverage statistics.
Optionally, provide doctests to illustrate usage. But keep in mind, doctests are not tests. Think of them as examples that happen to be tested.
It’s good idea to be sure that all existing tests pass and you don’t break anything, so please run:
pytest
To check also doctests, run:
pytest --doctest-modules
Please also check for potential flaws in your Python code with:
pylint diofant
and do type checking:
mypy diofant
If your change affects documentation, please build it by:
sphinx-build -W -b html docs build/sphinx/html
and check that it looks as expected.
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 our Github issues.
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 git history before
6f68fa1 - does mean issue sympy/sympy#3222
on Github.
Versioning
We use standard Semantic Versioning numbering scheme, but adopt PEP 440 for alpha (“aN” suffix), beta (“bN”) and development (“.devN”) releases.
Release Procedure
To release a new version, tag the latest commit in the master branch and publish this release tag:
git pull
git tag -s vX.Y.Z
git push origin vX.Y.Z