Skip to content

docs: rewrite CONTRIBUTING.md #660

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
petercorke wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: rewrite CONTRIBUTING.md #660

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 22 additions & 23 deletions .github/CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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).
Loading