How to contribute
This document describes how to contribute this project. There are several ways to contribute to this project as below:
Before contributing
Please check following items before contributing:
Understanding this project
Please check this What is PythonRobotics? section and this paper PythonRobotics: a Python code collection of robotics algorithms to understand the philosophies of this project.
Check your Python version.
We only accept a PR for Python 3.12.x or higher.
We will not accept a PR for Python 2.x.
1. Adding a new algorithm example
This is a step by step manual to add a new algorithm example.
Step 1: Choose an algorithm to implement
Before choosing an algorithm, please check the Getting Started doc to understand this project’s philosophy and setup your development environment.
If an algorithm is widely used and successful, let’s create an issue to propose it for our community.
If some people agree by thumbs up or posting positive comments, let go to next step.
It is OK to just create an issue to propose adding an algorithm, someone might implement it.
In that case, please share any papers or documentations to implement it.
Step 2: Implement the algorithm with matplotlib based animation
When you implement an algorithm, please keep the following items in mind.
Use only Python. Other language code is not acceptable.
This project only accept codes for python 3.9 or higher.
Use matplotlib based animation to show how the algorithm works.
Only use current Requirements libraries, not adding new dependencies.
Keep simple your code. The main goal is to make it easy for users to understand the algorithm, not for practical usage.
Step 3: Add a unittest
If you add a new algorithm sample code, please add a unit test file under tests dir.
This sample test code might help you : test_a_star.py.
At the least, try to run the example code without animation in the unit test.
If you want to run the test suites locally, you can use the runtests.sh script by just executing it.
The test_codestyle.py check code style for your PR’s codes.
Step 4: Write a document about the algorithm
Please add a document to describe the algorithm details, mathematical backgrounds and show graphs and animation gif.
This project is using Sphinx as a document builder, all documentations are written by reStructuredText.
You can add a new rst file under the subdirectory in doc modules dir and the top rst file can include it.
Please check other documents for details.
You can build the doc locally based on doc README.
For creating a gif animation, you can use this tool: matplotrecorder.
The created gif file should be stored in the PythonRoboticsGifs repository, so please create a PR to add it and refer to it in the doc.
Note that the reStructuredText based doc should only focus on the mathematics and the algorithm of the example.
Documentations related codes should be in the python script as the header comments of the script or docstrings of each function.
Step 5: Submit a pull request and fix codes based on review
Let’s submit a pull request when your code, test, and doc are ready.
At first, please fix all CI errors before code review.
You can check your PR doc from the CI panel.
After the “ci/circleci: build_doc” CI is succeeded, you can access you PR doc with clicking the [Details] of the “ci/circleci: build_doc artifact” CI.
After that, I will start the review.
Note that this is my hobby project; I appreciate your patience during the review process.
2. Reporting and fixing a defect
Reporting and fixing a defect is also great contribution.
When you report an issue, please provide these information:
A clear and concise description of what the bug is.
A clear and concise description of what you expected to happen.
Screenshots to help explain your problem if applicable.
OS version
Python version
Each library versions
If you want to fix any bug, you can find reported issues in bug labeled issues.
If you fix a bug of existing codes, please add a test function in the test code to show the issue was solved.
This doc submit a pull request can be helpful to submit a pull request.
3. Adding missed documentations for existing examples
Adding the missed documentations for existing examples is also great contribution.
If you check the Python Robotics Docs, you can notice that some of the examples only have a simulation gif or short overview descriptions or just TBD., but no detailed algorithm or mathematical description. These documents needs to be improved.
This doc how to write doc can be helpful to write documents.
4. Supporting this project
Supporting this project financially is also a great contribution!!.
If you or your company would like to support this project, please consider:
If you would like to support us in some other way, please contact with creating an issue.
Current Major Sponsors: