Basic Info

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-*.