Document release process from the point of view of users & downstream maintainers: pkg release, rosdistro PR, sync, patch release #5856
Description
Issue Type
- 🐛 Bug / Problem
- ✏️ Typo / Grammar
- 📖 Outdated Content
- 🚀 Enhancement
Generated by Generative AI
No
Distribution
No response
Description
I realized from interacting with users that the whole release process is not clear from the point of view of a downstream package maintainer. This is both about what happens to ROS 2 core packages (because downstream packages rely on them) and what happens to downstream packages. There is documentation for ROS core maintainers (e.g., release process and the aforementioned ROS Boss guide), but not for ecosystem package maintainers. The Releasing a Package how-to guides cover initial release tasks (indexing, first-time release) and subsequent releases, but that only covers blooming and opening a ros/rosdistro PR. That last guide mentions what happens after opening a ros/rosdistro PR (merged, built by buildfarm, available from testing repo, then from main repo after sync "every two to four weeks"), but it seems incomplete to me.
I would probably modify that last section to document the whole process from a downstream package maintainer's perspective: package release, ros/rosdistro PR, sync, patch release. Maybe as a simple timeline (with more details) using a numbered list? The only real difference between a ROS 2 core package and a downstream package here is probably that patch releases only include core packages.
As a concrete example, one of the goals with this is to avoid confusion like this: ros2/common_interfaces#285 (comment). A PR was backported to Humble to support something downstream in Nav2 @ Humble, and Steve was wondering why that PR's changes weren't reflected in the package's binaries from the apt repo after a Humble sync. In that case, the package hadn't been released after the backport PR was merged, so it wasn't rebuilt by the buildfarm and so a sync didn't do anything. If the whole process was a bit more known to non-core maintainers, perhaps Steve would've known to ask for a new release after the backport PR was merged (although the ROS Boss probably should've seen it and created a new release 👀).
Other instances where documentation would be good (at least to point to):
Other notes:
- Maybe mention status pages to see the status of a package? These are used heavily by ROS Bosses; I think they would also be useful to downstream maintainers, but they're never mentioned in the ROS 2 docs. https://repo.ros2.org/status_page/ros_rolling_default.html
Affected Pages/Sections
https://docs.ros.org/en/rolling/How-To-Guides/Releasing/Subsequent-Releases.html#next-steps
Screenshots or Examples (if applicable)
No response
Suggested Fix
No response
Additional Context
During my ~3 months as a temporary ROS Boss for Humble (covering for Audrow), I learned -- especially in the beginning -- to perform syncs and patch releases, which is documented in a GDoc called "ROS 2 ROS Boss Duties & Guidelines." Thankfully, I was already pretty familiar with these processes conceptually; I just needed to know the exact commands to run and buttons to push. However, this whole process/timeline isn't clear to downstream maintainers/users. I don't want to duplicate information in our docs, but I want to make this whole process more transparent for them.
And I realize that this also about educating people (spreading the knowledge) and not just about documenting it.