Added workflow to auto-tag docs PRs based on distro sync PRs. #5545

leander-dsouza · 2025-09-22T21:32:15Z

Note

Backport labels need to be created on ros-navigation/docs.nav2.org prior in order for tagging.

Basic Info

Info	Please fill out this column
Ticket(s) this addresses	#762
Documentation	N/A
Primary OS tested on	Ubuntu
Robotic platform tested on	N/A
Does this PR contain AI-generated software?	No
Was this PR description generated by AI software?	No

Description of contribution in a few bullet points

Added the ability to auto-tag ros-navigation/docs.nav2.org PRs with ROS Distro-specific backport labels.
The added workflow would trigger upon creation of a pull request with target branches to humble, jazzy, and kilted.
Then, the script would go through all the commits in the Sync PR, and would store all the PRs having #1234 in the title.
Then, using cross-references in these PRs, the target docs PR is found and labelled.
The added workflow would fail if the backports do not have any embedded doc PR associated with them.
Updated the PR template to include a documentation field.

Description of documentation updates required from your changes

Backport labels could be added to the Docs repository in the same way that the Nav2 repository does.
A mergify configuration could be set in place to facilitate backports based on the label.

Description of how this change was tested

The embedded logic can be tested out in the following bash script. Make sure log in using gh auth login if not configured before:

#!/bin/bash

PR_NUMBER=${1:-5539}

echo "Testing against PR #$PR_NUMBER"

# Determine ROS distro and label from PR title
pr_title=$(gh pr view $PR_NUMBER --repo ros-navigation/navigation2 --json title --jq '.title')
echo "PR Title: $pr_title"

if [[ "$pr_title" == *"Kilted Sync"* ]]; then
  ros_distro="kilted"
  label="backport-kilted"
elif [[ "$pr_title" == *"Jazzy Sync"* ]]; then
  ros_distro="jazzy"
  label="backport-jazzy"
fi

echo -e "\nProcessing $ros_distro sync with label: $label\n"

# Get PR numbers from commits
prs=$(gh api repos/ros-navigation/navigation2/pulls/$PR_NUMBER/commits \
  --jq '.[].commit.message' | grep -o '#[0-9]\+' | tr -d '#' | sort -u)

echo -e "Found PR numbers: $(echo $prs | tr '\n' ' ')\n"

# Find and label docs PRs
for pr in $prs; do

  # Get cross-referenced events
  docs_pr=$(gh api repos/ros-navigation/navigation2/issues/$pr/timeline \
    --jq '.[] | select(.event == "cross-referenced" and .source.issue.repository.name == "docs.nav2.org") |    .source.issue.number' \
    2>/dev/null | head -1)

  if [ -n "$docs_pr" ]; then
    echo "Found docs PR #$docs_pr for navigation2 PR #$pr"

    # Uncomment to actually apply labels:
    # echo "Labeling docs PR #$docs_pr with $label"
    # gh pr edit $docs_pr --repo ros-navigation/docs.nav2.org --add-label "$label"
  else
    echo "No cross-referenced docs PR found for navigation2 PR #$pr"
  fi
done

Expected Output:

Testing against PR #5539
PR Title: Kilted Sync Sept 19, 2025 1.4.2

Processing kilted sync with label: backport-kilted

Found PR numbers: 5452 5453 5478 5485 5488 5501 5506 5507 5514 5520 

No cross-referenced docs PR found for navigation2 PR #5452
No cross-referenced docs PR found for navigation2 PR #5453
No cross-referenced docs PR found for navigation2 PR #5478
Found docs PR #771 for navigation2 PR #5485
No cross-referenced docs PR found for navigation2 PR #5488
No cross-referenced docs PR found for navigation2 PR #5501
No cross-referenced docs PR found for navigation2 PR #5506
No cross-referenced docs PR found for navigation2 PR #5507
No cross-referenced docs PR found for navigation2 PR #5514
No cross-referenced docs PR found for navigation2 PR #5520

By default, the bash script targets Kilted Sync Sept 19, 2025 1.4.2 #5539; this can be passed as an argument as follows:
```
./test_tag.sh 5468
```
Note that in this example, the label would be empty. However, the linked docs PR would show up.
Since I do not have permissions to label, I think that once the labels are created in the Docs repository, this can be tested by the maintainers to verify its working.

Future work that may be required in bullet points

Upon successful review, we can include multi-branch support for the Docs repository.

For Maintainers:

Check that any new parameters added are updated in docs.nav2.org
Check that any significant change is added to the migration guide
Check that any new features OR changes to existing behaviors are reflected in the tuning guide
Check that any new functions have Doxygen added
Check that any new features have test coverage
Check that any new plugins is added to the plugins page
If BT Node, Additionally: add to BT's XML index of nodes for groot, BT package's readme table, and BT library lists
Should this be backported to current distributions? If so, tag with backport-*.

codecov · 2025-09-22T21:37:18Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
see 7 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

SteveMacenski · 2025-09-29T20:13:52Z

.github/workflows/autotag_docs.yml

+        run: |
+
+          # Testing permissions of github token (must be removed before merge)
+          gh pr edit 762 --repo ros-navigation/docs.nav2.org --add-label documentation


Should this still be here?

I added it as a method to show you that the secrets.GITHUB_TOKEN does not have enough permissions to label PRs in another repository within the same workspace.
I think the permissions for this secret need to be updated.

I have dropped it now for the review.

SteveMacenski · 2025-09-29T20:18:05Z

.github/workflows/autotag_docs.yml

+          # Determine ROS distro and label from PR title
+          pr_title="${{ github.event.pull_request.title }}"
+
+          if [[ "$pr_title" == *"Kilted Sync"* ]]; then


Is this because I name backport PRs as "XYZ Sync"?

Something to keep in mind is that I don't manually backport everything. Sometimes people backport themselves manually or are cherry picked using the backport-XYZ existing mergify job. If we only tagged PRs based on the PR title for my bulk backports, we'd miss alot

Maybe instead we should more generally just look at PRs that are targeting specific branches instead (i.e. the branch to be merged into is humble/jazzy/kilted). Then we can have the branch name in the matrix to run over and apply the label to respective docs PRs. That would then catch my backport syncs (independent of the PR name) and any other backports manually done by someone else or mergify.

In other words, we can use a build matrix workflow, whereas the matrix is set by branch name (which makes it very easy to add / remove them in the future). This job is triggered by a PR open against only one of those branches (humble, jazzy, etc) to attempt to look internally to that PR to find the doc PRs.

Thanks for the suggestion, Steve.
Yes, my initial thought was that all backports were titled as Distro Sync, but this is more accurate.

I have updated the workflow to run on specific targeted branches instead - kilted, jazzy, and humble.

SteveMacenski · 2025-09-29T20:23:45Z

.github/workflows/autotag_docs.yml

+              echo "Labeling docs PR #$docs_pr with '$label'"
+              gh pr edit $docs_pr --repo ros-navigation/docs.nav2.org --add-label "$label"
+            else
+              echo "No cross-referenced docs PR found for navigation2 PR #$pr"


If we know a PR is a backport and we don't find a docs PR, I think that's a legit reason to fail. We can then handle the failures on a case-by-case (i.e. no docs needed), but that way we know something was missed

I added a conditional that now fails, if the entire backport collection of PRs do not have any docs PRs associated with them at all.

SteveMacenski · 2025-09-29T20:24:30Z

A mergify configuration could be set in place to facilitate backports based on the label.

Like auto-opening a PR against that distro branch? Sounds nice!

SteveMacenski · 2025-09-29T20:25:11Z

I think we should also add a docs PR to our PR template so that they have a natural place to be set to link https://github.com/ros-navigation/navigation2/blob/main/.github/PULL_REQUEST_TEMPLATE.md and say that all PRs adding features, adding or changing parameters, or changing defaults need to have doc PRs.

leander-dsouza · 2025-09-30T22:28:29Z

A mergify configuration could be set in place to facilitate backports based on the label.

Like auto-opening a PR against that distro branch? Sounds nice!

Yes, indeed it does :)
To test this PR, backport labels need to be added in the Docs repository - backport-kilted, backport-jazzy, and backport-humble.

leander-dsouza · 2025-09-30T22:38:20Z

I think we should also add a docs PR to our PR template so that they have a natural place to be set to link https://github.com/ros-navigation/navigation2/blob/main/.github/PULL_REQUEST_TEMPLATE.md and say that all PRs adding features, adding or changing parameters, or changing defaults need to have doc PRs.

I have updated the PR template to include a Documentation field that encourages users to link the associated doc PR upon contribution.

Signed-off-by: Leander Stephen D'Souza <[email protected]>

leander-dsouza marked this pull request as ready for review September 22, 2025 21:37

leander-dsouza force-pushed the autotag-docs branch from a6341d9 to 6775b43 Compare September 22, 2025 21:44

leander-dsouza mentioned this pull request Sep 22, 2025

Added multi-branch support for master ros-navigation/docs.nav2.org#762

Open

leander-dsouza force-pushed the autotag-docs branch from 6775b43 to ba5efc4 Compare September 22, 2025 22:16

leander-dsouza marked this pull request as draft September 22, 2025 22:20

leander-dsouza force-pushed the autotag-docs branch 2 times, most recently from a3ce724 to 5224870 Compare September 22, 2025 22:32

leander-dsouza marked this pull request as ready for review September 22, 2025 22:32

SteveMacenski reviewed Sep 29, 2025

View reviewed changes

leander-dsouza force-pushed the autotag-docs branch from 5224870 to 23dffb2 Compare September 30, 2025 22:16

leander-dsouza requested a review from SteveMacenski October 1, 2025 01:50

leander-dsouza added 3 commits October 2, 2025 13:11

Added workflow to auto-tag docs PRs based on distro sync PRs.

9c68e0b

Signed-off-by: Leander Stephen D'Souza <[email protected]>

Label PRs against target branch, and fail if docs PRs are missing.

5be97e8

Signed-off-by: Leander Stephen D'Souza <[email protected]>

Updated PR template to include documentation link.

af9cd96

Signed-off-by: Leander Stephen D'Souza <[email protected]>

leander-dsouza force-pushed the autotag-docs branch from 90f77bc to af9cd96 Compare October 2, 2025 13:11

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Added workflow to auto-tag docs PRs based on distro sync PRs. #5545

Added workflow to auto-tag docs PRs based on distro sync PRs. #5545

leander-dsouza commented Sep 22, 2025 •

edited

Loading

Uh oh!

codecov bot commented Sep 22, 2025 •

edited

Loading

Uh oh!

SteveMacenski Sep 29, 2025

Uh oh!

leander-dsouza Sep 30, 2025 •

edited

Loading

Uh oh!

SteveMacenski Sep 29, 2025

Uh oh!

SteveMacenski Sep 29, 2025 •

edited

Loading

Uh oh!

leander-dsouza Sep 30, 2025

Uh oh!

SteveMacenski Sep 29, 2025

Uh oh!

leander-dsouza Sep 30, 2025

Uh oh!

SteveMacenski commented Sep 29, 2025

Uh oh!

SteveMacenski commented Sep 29, 2025 •

edited

Loading

Uh oh!

leander-dsouza commented Sep 30, 2025

Uh oh!

leander-dsouza commented Sep 30, 2025

Uh oh!

Uh oh!

Added workflow to auto-tag docs PRs based on distro sync PRs. #5545

Are you sure you want to change the base?

Added workflow to auto-tag docs PRs based on distro sync PRs. #5545

Conversation

leander-dsouza commented Sep 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Basic Info

Description of contribution in a few bullet points

Description of documentation updates required from your changes

Description of how this change was tested

Future work that may be required in bullet points

For Maintainers:

Uh oh!

codecov bot commented Sep 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

SteveMacenski Sep 29, 2025

Choose a reason for hiding this comment

Uh oh!

leander-dsouza Sep 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SteveMacenski Sep 29, 2025

Choose a reason for hiding this comment

Uh oh!

SteveMacenski Sep 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

leander-dsouza Sep 30, 2025

Choose a reason for hiding this comment

Uh oh!

SteveMacenski Sep 29, 2025

Choose a reason for hiding this comment

Uh oh!

leander-dsouza Sep 30, 2025

Choose a reason for hiding this comment

Uh oh!

SteveMacenski commented Sep 29, 2025

Uh oh!

SteveMacenski commented Sep 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

leander-dsouza commented Sep 30, 2025

Uh oh!

leander-dsouza commented Sep 30, 2025

Uh oh!

Uh oh!

leander-dsouza commented Sep 22, 2025 •

edited

Loading

codecov bot commented Sep 22, 2025 •

edited

Loading

leander-dsouza Sep 30, 2025 •

edited

Loading

SteveMacenski Sep 29, 2025 •

edited

Loading

SteveMacenski commented Sep 29, 2025 •

edited

Loading