From cd9c619040f3f98acaea9a67520c67b3d74b30e9 Mon Sep 17 00:00:00 2001 From: Peter Corke Date: Sat, 29 Aug 2026 17:30:27 +0200 Subject: [PATCH] docs: rewrite CONTRIBUTING.md Fixes two real defects (dead empty link at the end, stale black/flake8 references -- actual tooling is ruff), adds the Conventional Commits PR-title note (commitlint.yml already enforces it), and points at good-first-issue/help-wanted labels instead of nothing. Same structure now shared across RTB/MVTB/bdsim. --- .github/CONTRIBUTING.md | 45 ++++++++++++++++++++--------------------- 1 file changed, 22 insertions(+), 23 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 1851baf94..bd2ab329a 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,35 +1,34 @@ -# Contributing to the Robotics Toolbox +# Contributing to the Robotics Toolbox for Python -## Reporting issues - -When reporting issues please include as much detail as possible about your -operating system, roboticstoolbox version and python version. Whenever possible, please -also include a brief, self-contained code example that demonstrates the problem. - -## Contributing code +Thanks for your interest in contributing! We welcome bug reports, fixes, new features, and documentation improvements. -Thanks for your interest in contributing code! - -We welcome all kinds of contributions including: +## Reporting issues -+ New features -+ Bug and issue fixes -+ Cleaning, adding or adding to documentation and docstrings -+ Adding or fixing Python types +Please use the issue template and include: +- Your operating system, Python version, and roboticstoolbox version +- A short, self-contained code example that reproduces the problem -Keep in mind the following when making your contribution: +## Looking for somewhere to start? -+ Keep pull requests to a **single** feature/bug fix. This makes it much easier to review and merge. If you wish to contribure multiple different fixes or features, that means you should make multiple pull requests. +Issues labelled [`good first issue`](https://github.com/petercorke/robotics-toolbox-python/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) or [`help wanted`](https://github.com/petercorke/robotics-toolbox-python/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) are a good place to start. -+ For API changes, propose the API change in the discussions first before opening a pull request. +## Contributing code -+ Code additions should be formatted using [black](https://pypi.org/project/black/). Our configuration for black can be found in the [pyproject.toml](https://github.com/petercorke/robotics-toolbox-python/blob/master/pyproject.toml) file under the heading `[tool.black]`. Avoid reformatting code using other formatters. +- Keep pull requests scoped to a single feature or fix. If you have several unrelated changes, open separate PRs so each can be reviewed and merged independently. +- For API changes, propose the change in [Discussions](https://github.com/petercorke/robotics-toolbox-python/discussions) before opening a PR. +- PR titles follow [Conventional Commits](https://www.conventionalcommits.org/) (`type: description`) — checked automatically on the PR. +- Code is linted and formatted with [ruff](https://docs.astral.sh/ruff/); configuration is in `pyproject.toml` under `[tool.ruff]`. +- New or changed code should be type-hinted using modern syntax (`X | Y`, `X | None`, `list[X]`, `dict[K, V]` — not `Union`, `Optional`, `List`, `Dict`). +- Docstrings use reST style (`:param:`, `:returns:`). Type hints in the function signature already cover types, so `:type:`/`:rtype:` are rarely needed. +- Any code change should be covered by tests and must not break existing ones. Tests live in `tests/`. Install the dev dependencies with `pip install -e '.[dev]'` (add `,docs` too if you're touching documentation), then run: -+ Code addition should be linted using [flake8](https://pypi.org/project/flake8/). Our configuration for black can be found in the [pyproject.toml](https://github.com/petercorke/robotics-toolbox-python/blob/master/pyproject.toml) file under the heading `[tool.flake8]`. + ``` + pytest tests/ --ignore=tests/test_blocks.py --timeout=50 --timeout_method=thread -q + ``` -+ Any code addition needs to be covered by unit tests and not break existing tests. Our unit tests live in `robotics-toolbox-python/tests/`. You can install the dev dependencies using the command `pip install -e '.[dev,docs]'`. You can run the test suite using the command `pytest --cov=roboticstoolbox/ --cov-report term-missing`. Check the output to make sure your additions have been covered by the unit tests. +- Target branch is `main`. -+ All methods and classes need to be documented with an appropriate docstring. See our [style guide](https://github.com/petercorke/robotics-toolbox-python/wiki/Documentation-Style-Guide) for documentation. Keep the ordering and formatting as described by the style guide. +## License -+ New additions should be typed appropriately. See our typing [style guide](). +By contributing, you agree that your contributions will be licensed under this project's [MIT License](LICENSE).