diff --git a/docs/modules/0_getting_started/3_how_to_contribute_main.rst b/docs/modules/0_getting_started/3_how_to_contribute_main.rst index f975127107..47c6ffd623 100644 --- a/docs/modules/0_getting_started/3_how_to_contribute_main.rst +++ b/docs/modules/0_getting_started/3_how_to_contribute_main.rst @@ -30,6 +30,38 @@ We only accept a PR for Python 3.13.x or higher. We will not accept a PR for Python 2.x. +Before opening a pull request +-------------------------------- + +Check the items that apply to your change before opening a PR. The steps below +explain these points in more detail. + +- **Scope:** Focus on one algorithm, bug, or documentation topic. Split large + changes into smaller PRs, and propose substantial changes in an issue first. +- **Diff:** Use a separate branch and review the diff against ``master``. Remove + unrelated formatting, parameter, dependency, and CI configuration changes. +- **Readability:** Use descriptive names and small, clear functions. Keep the + code easy to relate to the algorithm's equations, even when optimizing it. +- **Compatibility:** Follow `Check your Python version.`_ and the current CI + configuration. Use only the existing :ref:`Requirements` libraries. +- **Existing behavior:** Preserve default parameters and working examples unless + the change is intentional and explained. Do not weaken tests to hide failures. +- **Tests:** For code changes, add or extend tests under ``tests`` that check the + expected result and relevant boundary cases. Run examples without animation + and run ``bash runtests.sh`` locally, including its code style checks. +- **Documentation:** Update the existing official RST page, or add one for a new + example. Explain the algorithm and mathematics there; explain code, inputs, + outputs, and units in headers and docstrings. Write these explanations in English. +- **Navigation and rendering:** Add new pages to the appropriate parent + ``toctree``. Build the docs and inspect the generated HTML, including equations, + lists, links, and images. +- **Animation:** For new examples or changed visual behavior, check that the + animation makes the result, colors, and lines understandable. Submit new GIFs + to `PythonRoboticsGifs`_ and link them from the documentation. +- **PR description:** Prepare the issue link, reason for the change, and test + results. Include before-and-after results where useful, and comparable timings + with the test configuration for performance improvements. + .. _`Adding a new algorithm example`: 1. Adding a new algorithm example @@ -60,13 +92,40 @@ When you implement an algorithm, please keep the following items in mind. 1. Use only Python. Other language code is not acceptable. -2. This project only accept codes for python 3.9 or higher. +2. Use the Python version described in `Check your Python version.`_ and run the + example with the versions used by the current CI configuration. -3. Use matplotlib based animation to show how the algorithm works. +3. Use matplotlib based animation to show how the algorithm works. Make the + start, goal, obstacles, and result clear where applicable, and explain the + meaning of colors and lines. The animation should help readers understand + the algorithm's behavior, such as how a path changes after detecting an obstacle. 4. Only use current :ref:`Requirements` libraries, not adding new dependencies. -5. Keep simple your code. The main goal is to make it easy for users to understand the algorithm, not for practical usage. +5. Keep the code simple and easy to follow. The main goal is to help beginners + understand the algorithm. Favor readability over performance or additional + abstractions, and keep the implementation recognizable from the algorithm's + equations. Avoid shortcuts that only work for the default simulation. + +6. Use descriptive names instead of unexplained abbreviations or single-letter + names. For example, prefer ``parent_index`` to ``pind``. If mathematical symbols + help relate the code to an equation, explain their meaning. Split long + functions and complex conditions into clearly named functions or intermediate + variables, and follow the style of nearby examples. + +7. Add a short file header describing the example, its author, and relevant + references. Use docstrings to explain functions, classes, inputs, outputs, + and configuration parameters, including units where applicable. Keep useful + existing explanations when refactoring. + +8. Use named configuration parameters instead of unexplained numeric constants. + Preserve existing defaults unless changing them is part of the intended fix; + set parameters for a particular test inside that test. + +9. Put the runnable example in a ``main()`` function and guard plotting with + ``show_animation`` so that the example also runs without animation. Prefer + existing Python, NumPy, SciPy, and project functions when they make the + algorithm easier to read, rather than duplicating the same implementation. Step 3: Add a unittest @@ -77,7 +136,21 @@ 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. +When extending an existing example, add test cases to its existing test file +where possible. Give tests descriptive names that explain the scenario, such as +``test_no_obstacle`` or ``test_too_big_step_size``. Cover the added algorithm +variants and relevant boundary cases. + +For a bug fix, reproduce the reported problem and assert the expected result, +not just that the code runs without an exception. Keep existing tests and default +examples working. Do not weaken an assertion merely to make a changed algorithm +pass; explain and test any intentional change in behavior. + +Run the test suite locally from the repository root: + +.. code-block:: bash + + bash runtests.sh The `test_codestyle.py`_ check code style for your PR's codes. @@ -86,16 +159,28 @@ 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. +Please describe the algorithm's basic steps, mathematical background, and +relevant references, with graphs and an animation GIF. Explain how it differs +from related algorithms and where it is useful when this helps readers +understand the example. 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. +For an existing example, update its official document instead of creating a +separate README or a duplicate explanation. For a new example, add a +``*_main.rst`` page under the appropriate category in `doc modules dir`_ and +include it in the parent page's ``toctree``. Follow the naming and toctree entries +of nearby pages so that the new page appears in the documentation navigation. Please check other documents for details. You can build the doc locally based on `doc README`_. +After building, open the generated HTML or the PR's documentation artifact and +check the changed pages. Confirm that equations, lists, links, images, and +animations render correctly, and that the page is reachable from its parent. +A successful build alone does not guarantee that the page looks correct. + For creating a gif animation, you can use this tool: `matplotrecorder`_. The created gif file should be stored in the `PythonRoboticsGifs`_ repository, @@ -125,10 +210,21 @@ When you click the link, you will jump to the source code in Github like: 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. +Use the `Before opening a pull request`_ checklist, then submit your PR when the +code, tests, and documentation are ready. + +In the PR description, link the relevant issue and explain the problem, why the +change solves it, and how you tested it. For changes to a simulation, include +before-and-after results or animations where useful. For a performance +improvement, explain the technique and provide comparable timings and the +configuration used to obtain them. At first, please fix all CI errors before code review. +Check the test, code style, and documentation build results. If a failure appears +unrelated to your changes, report the failing check and relevant log rather than +changing CI settings or removing tests to hide the failure. + You can check your PR doc from the CI panel. After the "ci/circleci: build_doc" CI is succeeded, @@ -162,6 +258,8 @@ 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. +Use the failing inputs as a regression case and assert the corrected behavior, +including relevant boundary conditions. Keep unrelated changes in separate PRs. This doc `submit a pull request`_ can be helpful to submit a pull request. @@ -223,5 +321,3 @@ Current Major Sponsors: .. _`matplotrecorder`: https://github.com/AtsushiSakai/matplotrecorder .. _`PythonRoboticsGifs`: https://github.com/AtsushiSakai/PythonRoboticsGifs .. _`autodoc`: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html - -