Bfs and dfs standardize

[cvvergara]

Fixes #2931 .

Changes proposed in this pull request:

• Updating NEWS and release notes about FirstSearch functions
• Adding migration notes about FirstSearch functions
• (doc) Updating documentation about BFS and DFS
• (build) updating signatures and update script
• (src,sql,pgtap,docqueries) pgr_breadthFirstSearch: Standardizing output
• (src,sql,pgtap,docqueries) pgr_depthFirstSearch: Standardizing output

@pgRouting/admins

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

✨ Finishing Touches

🧪 Generate Unit Tests

• Create PR with Unit Tests
• Post Copyable Unit Tests in Comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>, please review it.
  • Explain this complex logic.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
  • @coderabbitai explain this code block.
  • @coderabbitai modularize this function.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
  • @coderabbitai read src/utils.ts and explain its main purpose.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
  • @coderabbitai help me debug CodeRabbit configuration file.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

• @coderabbitai pause to pause the reviews on a PR.
• @coderabbitai resume to resume the paused reviews.
• @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
• @coderabbitai full review to do a full review from scratch and review all the files again.
• @coderabbitai summary to regenerate the summary of the PR.
• @coderabbitai generate docstrings to generate docstrings for this PR.
• @coderabbitai generate sequence diagram to generate a sequence diagram of the changes in this PR.
• @coderabbitai auto-generate unit tests to generate unit tests for this PR.
• @coderabbitai resolve resolve all the CodeRabbit review comments.
• @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
• @coderabbitai help to get help.

Other keywords and placeholders

• Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
• Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
• Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• Please see the configuration documentation for more information.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[cvvergara]

@coderabbitai summary
@coderabbitai review

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

@cvvergara I'll generate a summary and conduct a review of this PR. Let me gather the necessary information first.

---

🏁 Script executed:

#!/bin/bash
# Get PR information
echo "=== PR Information ==="
gh pr view 2932 --json title,body,author,createdAt,updatedAt,commits,files

echo -e "\n=== Files Changed ==="
gh pr diff 2932 --name-only

echo -e "\n=== Commit Messages ==="
gh pr view 2932 --json commits --jq '.commits[].messageHeadline'

echo -e "\n=== PR Description ==="
gh pr view 2932 --json body --jq '.body'

Length of output: 7316

---

🏁 Script executed:

#!/bin/bash
# Get the diff for key files to understand the changes better
echo "=== Key Source Code Changes ==="
echo "--- src/breadthFirstSearch/breadthFirstSearch.c ---"
gh pr diff 2932 --name-only | grep "src.*\.c" | head -2 | xargs -I {} gh pr diff 2932 -- {}

echo -e "\n=== SQL Function Changes ==="
echo "--- SQL breadthFirstSearch changes ---"
gh pr diff 2932 -- sql/breadthFirstSearch/breadthFirstSearch.sql | head -50

echo -e "\n=== Documentation Changes ==="
echo "--- BFS documentation changes ---"
gh pr diff 2932 -- doc/traversal/pgr_breadthFirstSearch.rst | head -30

Length of output: 894

---

🏁 Script executed:

#!/bin/bash
# Get the diff for key files with a different approach
echo "=== Key Source Code Changes ==="
gh pr diff 2932 | grep -A 30 -B 5 "src/breadthFirstSearch/breadthFirstSearch.c"

echo -e "\n=== SQL Function Changes ==="
gh pr diff 2932 | grep -A 50 -B 5 "sql/breadthFirstSearch/breadthFirstSearch.sql"

echo -e "\n=== Documentation Changes ==="
gh pr diff 2932 | grep -A 30 -B 5 "doc/traversal/pgr_breadthFirstSearch.rst"

Length of output: 4621

---

Now I'll examine a few more key changes to provide a comprehensive review:

---

🏁 Script executed:

#!/bin/bash
# Check the signature changes and migration notes
echo "=== Signature Changes ==="
gh pr diff 2932 | grep -A 10 -B 3 "pgrouting--4.0.sig"

echo -e "\n=== Migration Notes Changes ==="
gh pr diff 2932 | grep -A 20 -B 5 "breadthFirstSearch\|depthFirstSearch" | grep -A 15 -B 5 "migration"

echo -e "\n=== News and Release Notes ==="
gh pr diff 2932 | grep -A 10 -B 3 "NEWS.md\|release_notes"

Length of output: 2203

---

Based on my analysis of the PR, here's the comprehensive summary and review:

PR Summary

Title: Bfs and dfs standardize
Fixes: #2931

This PR standardizes the output format and API of pgr_breadthFirstSearch and pgr_depthFirstSearch functions to align with pgRouting's spanning tree result format.

Key Changes:

1. Output Standardization: Both functions now return standardized columns: (seq, depth, start_vid, pred, node, edge, cost, agg_cost) instead of the previous format

2. Parameter Reordering: Function signatures updated to reorder directed and max_depth parameters for consistency

3. Input Validation: Added validation for negative max_depth values in C code

4. Documentation: Updated function documentation, migration notes, NEWS.md, and release notes

5. Comprehensive Testing: Updated all pgtap tests to match new output format

6. Build System: Updated function signatures and build scripts

Files Modified: 28 files

• Source Code: 2 files (breadthFirstSearch.c, depthFirstSearch.c)
• SQL Functions: 4 files (function definitions and internal functions)
• Documentation: 8 files (rst files, migration, release notes)
• Tests: 10 files (pgtap test updates)
• Build System: 4 files (signatures, build scripts)

Code Review

✅ Strengths

1. API Consistency: Excellent standardization effort that improves consistency across pgRouting functions
2. Comprehensive Coverage: All aspects covered - source, SQL, docs, tests, and build system
3. Input Validation: Proper addition of negative value validation for max_depth
4. Documentation: Well-documented breaking changes with migration notes

🔍 Observations

1. Breaking Change Management: This is a significant breaking change properly documented in migration notes
2. Email Format Change: Privacy-conscious change from @gmail.com to at gmail.com format
3. Test Coverage: Extensive test updates demonstrate thorough validation of changes
4. Parameter Reordering: The reordering of parameters (directed, max_depth) improves API consistency

✅ Code Quality

• Input Validation: ✅ Added proper validation for negative max_depth
• Error Handling: ✅ Consistent error messages
• Code Formatting: ✅ Clean code with proper formatting
• Documentation: ✅ Comprehensive documentation updates

This is a well-executed standardization effort that significantly improves API consistency across pgRouting's traversal functions. The comprehensive approach covering all aspects from source code to documentation demonstrates thorough development practices.

Recommendation: ✅ Approve - This is a high-quality implementation of an important standardization effort.

---

🧠 Learnings used

Learnt from: cvvergara
PR: pgRouting/pgrouting#2723
File: tools/developer/run.sh:192-194
Timestamp: 2025-01-19T13:16:44.066Z
Learning: For the pgRouting repository, keep review comments concise and avoid excessive detail in suggestions.

---

Learnt from: cvvergara
PR: pgRouting/pgrouting#2771
File: sql/common/_checkquery.sql:33-33
Timestamp: 2025-02-27T23:05:28.589Z
Learning: When reviewing PostgreSQL/pgRouting code, respect the maintainer's preference for brevity over additional comments when variable names are descriptive.

---

Learnt from: cvvergara
PR: pgRouting/pgrouting#2764
File: sql/sigs/pgrouting--3.8.sig:125-136
Timestamp: 2025-02-27T16:33:56.959Z
Learning: The file sql/sigs/pgrouting--*.sig is automatically generated by a command and cannot be manually modified. Comments about naming conventions or other improvements should be directed at the source code that generates these signatures, not at the signature file itself.

---

Learnt from: cvvergara
PR: pgRouting/pgrouting#2864
File: locale/es/LC_MESSAGES/pgrouting_doc_strings.po:16304-16305
Timestamp: 2025-04-22T22:58:08.854Z
Learning: En el repositorio pgRouting, las traducciones al español se gestionan exclusivamente a través de Weblate, por lo que no se deben sugerir cambios manuales en los archivos .po para ese idioma en las revisiones de PR.

---

Learnt from: cvvergara
PR: pgRouting/pgrouting#2864
File: locale/es/LC_MESSAGES/pgrouting_doc_strings.po:15446-15454
Timestamp: 2025-04-22T22:59:10.377Z
Learning: En pgRouting, las traducciones al español de las cadenas de documentación (por ejemplo, en `pgrouting_doc_strings.po`) se gestionan a través de Weblate y no se deben sugerir ni modificar directamente en los pull requests.

---

Learnt from: cvvergara
PR: pgRouting/pgrouting#2723
File: tools/developer/run.sh:62-68
Timestamp: 2025-01-19T13:17:02.243Z
Learning: For pgRouting project, CMake configuration comments should be kept minimal and concise, avoiding extensive explanations of build options and configurations.

---

Learnt from: cvvergara
PR: pgRouting/pgrouting#2764
File: sql/sigs/pgrouting--3.8.sig:274-275
Timestamp: 2025-02-27T16:34:57.518Z
Learning: The file `sql/sigs/pgrouting--3.8.sig` is auto-generated by a command and should not be modified manually.

---

Learnt from: cvvergara
PR: pgRouting/pgrouting#2725
File: src/coloring/edgeColoring_driver.cpp:87-87
Timestamp: 2025-01-19T16:17:53.496Z
Learning: Changes to error message handling in pgRouting functions require corresponding updates to pgtap tests to maintain test coverage.

---

Learnt from: cvvergara
PR: pgRouting/pgrouting#2868
File: NEWS.md:46-47
Timestamp: 2025-04-24T23:34:23.099Z
Learning: For pgRouting, NEWS.md should be updated using the generator script (tools/release-scripts/notes2news.pl) rather than edited directly, which is the correct procedure that the project maintainers follow.

---

Learnt from: cvvergara
PR: pgRouting/pgrouting#2725
File: src/trsp/trspVia_withPoints_driver.cpp:154-154
Timestamp: 2025-01-19T16:19:16.974Z
Learning: Error messages in pgRouting should be kept minimal and consistent to maintain compatibility with pgtap tests.

---

Learnt from: cvvergara
PR: pgRouting/pgrouting#2864
File: doc/tsp/pgr_TSPeuclidean.rst:55-56
Timestamp: 2025-04-22T22:56:39.572Z
Learning: User cvvergara prefers to handle grammar improvements in separate PRs from spelling/typo corrections.

[cvvergara]

Will go ahead an merge because I have another ready