petercorke / petercorke/robotics-toolbox-python

rtb-data packaging and release-please process

Open
#573 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

tech-debt
Dominant language
C++
Stars
3.5k
Forks
624
Avg merge
2d 4h
Merged PRs (30d)
53

Description

Migrated from tech-debt.md (deleted, see repo history via git log -- tech-debt.md). Groups rtb-data packaging and the release-please/CI process work that's entangled with it.

  • Automate rtb-data publishing alongside roboticstoolbox-python releases, only when it actually changed. rtb-data is a separate PyPI package (meshes, xacro/URDF sources) built from rtb-data/, published independently. The main release process (release-please + release.yml) knows nothing about it -- as of 2026-07-03 rtb-data/ on main had drifted well ahead of PyPI (missing rtb-data/pyproject.toml entirely at one point), causing CI failures from xacro files the installed PyPI package didn't have yet. Proposed: a CI step that diffs rtb-data/ against the tree at the last rtb-data publish (tag or recorded SHA); no-op if unchanged, bump + publish if changed. Deliberately not "publish rtb-data on every release" -- it's large (meshes, STL/OBJ) and should stay infrequent.

  • Move rtb-data/ into a packages/ folder. Currently sits at repo root alongside the main source tree despite being independently versioned/published. Only two files reference the path (pyproject.toml's sdist.exclude, rtb-data/pyproject.toml itself), so the move is cheap. Worth doing since GRAPHICS-BACKEND.md/SWIFT-MPL-SPLIT.md both describe splitting graphics backends into further sub-packages -- better to establish the packages/ convention with one occupant than reshuffle after two or three exist. Sequence before the publishing-automation item above, so that's built against the final path.

  • Credit robot_descriptions in docstrings of the models that load via it. At least 8 model classes (Fetch, Frankie, Jaco, PR2, UR10, UR3, UR5, Valkyrie, YuMi) load via robot_descriptions under the hood, but none of their docstrings say so -- a user reading e.g. UR5's docstring has no way to know the model comes from a third-party package. Add a line naming robot_descriptions with a link to its repo (same URL already used in URDFRobot.py's _RD_URL constant -- reuse it so the two don't drift). Mechanical, low-risk, ~8 files.

  • Extend release-please to understand rtb-data as a second component. release-please here only tracks one linear history (. = roboticstoolbox-python) off main's tip -- no concept of releasing from an older point, and no concept of rtb-data/ as a second component. This is why out-of-band maintenance-branch releases (e.g. maintenance/1.3.x off an old tag, bypassing release-please entirely) have been needed when main moved on to in-progress/breaking work before a fix could ship for the currently-released version. Fixing the multi-package gap removes the main reason for doing those. Related operating pattern to keep either way: land CI-health fixes directly against main as small independent PRs, don't stack feature/fix work on top of other unmerged fix PRs -- get main green first. Also note: there is no approval gate on the pypi deployment environment (confirmed via GitHub API) -- a successful build publishes to PyPI immediately once a GitHub Release is created, no dry-run. Always rehearse locally first (python -m build, install into a real throwaway venv).

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading rtb-data/pyproject.toml, the root pyproject.toml exclusions, release.yml, and the release-please configuration, then inspect the model docstrings and URDFRobot.py's _RD_URL. Map the package move before assessing publishing and multi-component release behavior. Done means the four checklist areas are implemented, CI and PyPI publishing behavior are verified, and the affected model documentation names robot_descriptions.

Written by the indexing model from the issue text.

Assessment

Tech stack
github-actions, python
Domain
build-system, ci-cd, documentation, release
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.