Promotion of functions to official

[cvvergara]

Fixes #2700 #2701 #2718
.

Changes proposed in this pull request:

• Modification on documentation about official functions
• Remove PROPOSED keyword on sql files of the official functions

@pgRouting/admins

Summary by CodeRabbit

Release Notes for pgRouting 4.0.0

• New Features

  • Promoted multiple functions to official status, including pgr_trsp, pgr_withPoints, and related variants
  • Added support for combination signatures in various routing functions
  • Enhanced parameter flexibility for routing functions

• Improvements

  • Updated function signatures to support array inputs for vertices
  • Added new routing scenarios for one-to-many, many-to-one, and many-to-many configurations
  • Improved documentation for function parameters and usage

• Deprecated Functions

  • Removed several deprecated functions, including pgr_trspviaedges and pgr_trspviavertices

• Documentation

  • Clarified function statuses and promoted previously proposed functions to official

[coderabbitai]

Walkthrough

The pull request introduces significant updates to the pgRouting library, focusing on promoting the WithPoints family of functions from proposed to official status in version 4.0.0. This includes multiple functions like pgr_withPoints, pgr_withPointsCost, pgr_withPointsKSP, and others. The changes involve updating documentation, modifying function signatures to support more flexible input types (such as using ANYARRAY), and removing "proposed" labels from various function descriptions.

Changes

File/Path	Change Summary
NEWS.md	Added section detailing functions promoted to official status
doc/*/pgr_withPoints*.rst	Updated documentation to remove "Proposed" labels, added version 4.0.0
sql/withPoints/*.sql	Modified function signatures to support more input scenarios
doc/src/release_notes.rst	Added sections for officially promoted functions and signatures

Assessment against linked issues

Objective	Addressed	Explanation
Promote pgr_withPoints	✅
Promote pgr_withPointsCost	✅
Promote pgr_withPointsCostMatrix	✅
Promote pgr_withPointsKSP	✅
Promote pgr_withPointsDD	✅
Promote pgr_withPointsVia	✅

Poem

🐰 Routing rabbits hop with glee,
WithPoints functions now set free!
From proposed to official state,
Our pgRouting library just got great!
Flexibility hops, signatures dance,
A routing revolution at first glance! 🚗🗺️

---

📜 Recent review details

Configuration used: CodeRabbit UI
Review profile: ASSERTIVE
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 7fefaf7 and 94848a0.

📒 Files selected for processing (35)

• NEWS.md (1 hunks)
• doc/astar/pgr_aStar.rst (2 hunks)
• doc/astar/pgr_aStarCost.rst (2 hunks)
• doc/bdAstar/pgr_bdAstar.rst (2 hunks)
• doc/bdAstar/pgr_bdAstarCost.rst (2 hunks)
• doc/bdDijkstra/pgr_bdDijkstra.rst (2 hunks)
• doc/bdDijkstra/pgr_bdDijkstraCost.rst (2 hunks)
• doc/dijkstra/pgr_dijkstra.rst (2 hunks)
• doc/dijkstra/pgr_dijkstraCost.rst (2 hunks)
• doc/ksp/pgr_KSP.rst (5 hunks)
• doc/max_flow/pgr_boykovKolmogorov.rst (2 hunks)
• doc/max_flow/pgr_edmondsKarp.rst (2 hunks)
• doc/max_flow/pgr_maxFlow.rst (2 hunks)
• doc/max_flow/pgr_pushRelabel.rst (2 hunks)
• doc/src/release_notes.rst (1 hunks)
• doc/trsp/pgr_trsp.rst (7 hunks)
• doc/trsp/pgr_trspVia.rst (2 hunks)
• doc/trsp/pgr_trspVia_withPoints.rst (2 hunks)
• doc/trsp/pgr_trsp_withPoints.rst (6 hunks)
• doc/withPoints/pgr_withPoints.rst (6 hunks)
• doc/withPoints/pgr_withPointsCost.rst (6 hunks)
• doc/withPoints/pgr_withPointsCostMatrix.rst (1 hunks)
• doc/withPoints/pgr_withPointsDD.rst (3 hunks)
• doc/withPoints/pgr_withPointsKSP.rst (6 hunks)
• doc/withPoints/pgr_withPointsVia.rst (2 hunks)
• sql/driving_distance/withPointsDD.sql (0 hunks)
• sql/ksp/withPointsKSP.sql (0 hunks)
• sql/trsp/trsp.sql (0 hunks)
• sql/trsp/trspVia.sql (0 hunks)
• sql/trsp/trspVia_withPoints.sql (0 hunks)
• sql/trsp/trsp_withPoints.sql (0 hunks)
• sql/withPoints/withPoints.sql (0 hunks)
• sql/withPoints/withPointsCost.sql (0 hunks)
• sql/withPoints/withPointsCostMatrix.sql (0 hunks)
• sql/withPoints/withPointsVia.sql (0 hunks)

💤 Files with no reviewable changes (10)

• sql/withPoints/withPointsCostMatrix.sql
• sql/trsp/trspVia.sql
• sql/trsp/trspVia_withPoints.sql
• sql/trsp/trsp.sql
• sql/withPoints/withPointsCost.sql
• sql/withPoints/withPoints.sql
• sql/withPoints/withPointsVia.sql
• sql/driving_distance/withPointsDD.sql
• sql/trsp/trsp_withPoints.sql
• sql/ksp/withPointsKSP.sql

🧰 Additional context used

🪛 Markdownlint (0.37.0)

NEWS.md

44-44: Expected: 1; Actual: 2
Multiple consecutive blank lines

(MD012, no-multiple-blanks)

---

15-15: null
Emphasis used instead of a heading

(MD036, no-emphasis-as-heading)

---

28-28: null
Emphasis used instead of a heading

(MD036, no-emphasis-as-heading)

---

12-12: null
Spaces inside link text

(MD039, no-space-in-links)

🪛 LanguageTool

NEWS.md

[uncategorized] ~11-~11: Possible missing comma found.
Context: ...l issues & pull requests closed by this release see the [Git closed milestone for 4.0.0...

(AI_HYDRA_LEO_MISSING_COMMA)

⏰ Context from checks skipped due to timeout of 90000ms (2)

• GitHub Check: Codacy Static Code Analysis
• GitHub Check: Check queries

🔇 Additional comments (40)

doc/withPoints/pgr_withPointsKSP.rst (3)

23-25: LGTM: Version information and status change is well documented.

The promotion to official status is clearly documented with the appropriate version number.

---

Line range hint 169-269: LGTM: Parameter documentation is comprehensive and well-structured.

The parameter descriptions are thorough, with clear types, constraints, and examples. The separation of optional parameters and their descriptions is particularly well done.

---

Line range hint 270-350: LGTM: Examples are comprehensive and well-documented.

The examples effectively demonstrate various use cases, including integration with other functions like pgr_findCloseEdges. The documentation structure follows RST best practices.

doc/withPoints/pgr_withPointsCost.rst (4)

11-13: Index entries correctly updated for official status.

The index entries have been properly updated to reflect the function's promotion to official status while maintaining appropriate categorization.

---

27-30: Version history properly documented.

The promotion to official status is clearly documented with the correct version number (4.0.0), while maintaining the historical version information.

---

114-114: Signature index entries correctly updated.

All function signature variations have been properly indexed without the "Proposed" status, maintaining clear categorization for each type (One to One, One to Many, Many to One, Many to Many, and Combinations).

Also applies to: 135-135, 157-157, 178-178, 200-200

---

Line range hint 1-400: Verify documentation consistency.

The documentation has been properly updated to reflect the function's official status. Let's verify that no "Proposed" labels remain in the documentation.

✅ Verification successful

Historical references to "Proposed" status are correct

The remaining instances of "Proposed" are in the version history section, documenting the function's evolution from proposed to official status. These historical references should be preserved.

🏁 Scripts executed

The following scripts were executed for the analysis:

Script:

#!/bin/bash
# Description: Check for any remaining "Proposed" labels in the documentation
# that might have been missed during the update.

echo "Checking for any remaining 'Proposed' labels..."
rg -i "proposed" "doc/withPoints/pgr_withPointsCost.rst"

Length of output: 220

doc/withPoints/pgr_withPointsCostMatrix.rst (1)

11-14: Documentation updates are accurate and well-structured.

The changes correctly reflect the promotion of pgr_withPointsCostMatrix to official status in version 4.0.0, with appropriate updates to index entries and version history.

Also applies to: 26-29

doc/max_flow/pgr_edmondsKarp.rst (1)

24-27: Documentation updates correctly reflect the promotion of Combinations signature.

The changes accurately document the promotion of the Combinations signature to official status in version 4.0.0, with appropriate updates to version history and index entries.

Also applies to: 157-157

doc/max_flow/pgr_pushRelabel.rst (1)

24-27: Documentation updates maintain consistency with related functions.

The changes appropriately document the promotion of the Combinations signature to official status, maintaining consistency with related max flow functions.

Also applies to: 157-157

doc/max_flow/pgr_boykovKolmogorov.rst (1)

24-27: Documentation updates align with max flow family changes.

The changes correctly document the promotion of the Combinations signature to official status, maintaining consistency with other max flow functions.

Also applies to: 157-157

doc/max_flow/pgr_maxFlow.rst (1)

24-27: Documentation updates complete the max flow family changes.

The changes appropriately document the promotion of the Combinations signature to official status, maintaining consistency across the max flow family of functions.

Also applies to: 154-154

doc/withPoints/pgr_withPointsVia.rst (1)

26-28: LGTM! Version and promotion note added correctly.

The changes properly document the promotion of the function to official status in version 4.0.0.

doc/bdDijkstra/pgr_bdDijkstra.rst (2)

24-26: LGTM! Version and promotion note added correctly.

The changes properly document the promotion of the Combinations signature to official status in version 4.0.0.

---

169-169: LGTM! Index entry updated correctly.

The index entry for Combinations has been properly updated to reflect its official status.

doc/bdDijkstra/pgr_bdDijkstraCost.rst (2)

24-26: LGTM! Version and promotion note added correctly.

The changes properly document the promotion of the Combinations signature to official status in version 4.0.0.

---

160-160: LGTM! Index entry updated correctly.

The index entry for Combinations has been properly updated to reflect its official status.

doc/dijkstra/pgr_dijkstraCost.rst (2)

26-28: LGTM! Version and promotion note added correctly.

The changes properly document the promotion of the Combinations signature to official status in version 4.0.0.

---

162-162: LGTM! Index entry updated correctly.

The index entry for Combinations has been properly updated to reflect its official status.

doc/trsp/pgr_trsp.rst (2)

25-27: LGTM! Version and promotion note added correctly.

The changes properly document the promotion of the function to official status in version 4.0.0.

---

80-80: LGTM! Index entries and rubric updated correctly.

All index entries have been properly updated to reflect the official status, and the rubric has been appropriately changed from "Proposed" to "Summary".

Also applies to: 95-95, 115-115, 136-136, 157-157, 179-179

doc/trsp/pgr_trspVia.rst (1)

18-18: Documentation updates are accurate and consistent.

The changes correctly reflect the promotion of pgr_trspVia to official status in version 4.0.0.

Let's verify the consistency of this promotion across related files:

Also applies to: 25-27

✅ Verification successful

Documentation promotion is fully consistent across all files

The promotion of pgr_trspVia to official status is correctly reflected across:

• Release notes listing it as officially promoted in 4.0.0
• TRSP family documentation
• Via category documentation
• Migration guide references

🏁 Scripts executed

The following scripts were executed for the analysis:

Script:

#!/bin/bash
# Description: Check for any remaining "proposed" references to pgr_trspVia
rg -i "proposed.*pgr_trspVia|pgr_trspVia.*proposed" --type rst

Length of output: 64

---

Script:

#!/bin/bash
# Search for all references to pgr_trspVia
rg "pgr_trspVia" --type rst -l

# Check version history mentions
rg -i "4\.0\.0.*pgr_trspVia|pgr_trspVia.*4\.0\.0" --type rst

# Check if listed in official functions index
rg "pgr_trspVia" doc/index.rst doc/**/index.rst

Length of output: 423

---

Script:

#!/bin/bash
# Check release notes and migration guide content
rg -A 5 -B 5 "pgr_trspVia" doc/src/release_notes.rst doc/src/migration.rst

# Check category listings and family documentation
rg -A 2 -B 2 "pgr_trspVia" doc/categories/via-category.rst doc/categories/withPoints-category.rst doc/trsp/TRSP-family.rst

Length of output: 8518

doc/astar/pgr_aStarCost.rst (1)

24-27: Documentation updates are accurate and maintain family consistency.

The changes correctly reflect the promotion of the Combinations signature to official status in version 4.0.0, maintaining consistency with other A* family functions.

Let's verify the consistency across the A* family documentation:

Also applies to: 178-178

✅ Verification successful

Documentation changes are consistent across A family functions*

The version 4.0.0 update for Combinations signature promotion is consistently documented in both relevant A* family functions (pgr_aStar and pgr_aStarCost). The pgr_aStarCostMatrix function correctly doesn't include this change as it doesn't support the Combinations signature.

🏁 Scripts executed

The following scripts were executed for the analysis:

Script:

#!/bin/bash
# Description: Check for consistency in A* family documentation
# Verify all A* family functions show the same version for Combinations promotion
rg -A 5 "Version 4\.0\.0" --type rst doc/astar/

Length of output: 532

---

Script:

#!/bin/bash
# Find all A* documentation files and check for Combinations mentions
echo "=== All A* family documentation files ==="
fd "^pgr_a.*\.rst$" doc/astar/

echo -e "\n=== Files mentioning Combinations ==="
rg -l "Combinations" doc/astar/

Length of output: 386

doc/bdAstar/pgr_bdAstarCost.rst (1)

24-27: Documentation updates maintain bidirectional A family consistency.*

The changes correctly reflect the promotion of the Combinations signature to official status, maintaining consistency with other bidirectional A* family functions.

Let's verify the consistency across the bidirectional A* family documentation:

Also applies to: 178-178

✅ Verification successful

Bidirectional A family documentation is consistent*

Both pgr_bdAstar and pgr_bdAstarCost documentation files correctly and consistently document the promotion of Combinations signature to official status in Version 4.0.0.

🏁 Scripts executed

The following scripts were executed for the analysis:

Script:

#!/bin/bash
# Description: Check for consistency in bidirectional A* family documentation
# Verify all bdA* family functions show the same version for Combinations promotion
rg -A 5 "Version 4\.0\.0" --type rst doc/bdAstar/

Length of output: 582

doc/astar/pgr_aStar.rst (1)

23-26: Documentation updates align with A family changes.*

The changes correctly reflect the promotion of the Combinations signature to official status, maintaining consistency across the A* function family.

Let's verify the consistency of function signatures across A* implementations:

Also applies to: 191-191

✅ Verification successful

Documentation changes are consistent across A family functions*

The promotion of Combinations signature to official status in version 4.0.0 is correctly documented in both pgr_aStar.rst and pgr_aStarCost.rst. The pgr_aStarCostMatrix.rst appropriately doesn't include these changes as it serves a different purpose and doesn't support the Combinations signature.

🏁 Scripts executed

The following scripts were executed for the analysis:

Script:

#!/bin/bash
# Description: Check for consistency in A* function signatures
# Verify all A* functions have the same signature patterns
ast-grep --pattern 'pgr_aStar\(`Edges SQL`_, `Combinations SQL`_, \[**options**\]\)' doc/astar/

Length of output: 97

---

Script:

#!/bin/bash
# Find all A* documentation files and check version/signature information
echo "=== A* Documentation Files ==="
fd -e rst -p 'a[sS]tar' doc/

echo -e "\n=== Version 4.0.0 Mentions ==="
rg -l "Version 4\.0\.0" doc/astar/

echo -e "\n=== Combinations Signature References ==="
rg -B2 -A2 "Combinations signature" doc/astar/

Length of output: 957

---

Script:

#!/bin/bash
# Check pgr_aStarCostMatrix.rst for combinations-related content
echo "=== aStarCostMatrix Combinations Check ==="
rg -A 5 "Synopsis" doc/astar/pgr_aStarCostMatrix.rst

echo -e "\n=== aStarCostMatrix Version History ==="
rg "Version" doc/astar/pgr_aStarCostMatrix.rst

Length of output: 321

doc/bdAstar/pgr_bdAstar.rst (1)

23-26: Documentation updates complete the A family consistency.*

The changes correctly reflect the promotion of the Combinations signature to official status, maintaining consistency across all A* and bidirectional A* functions.

Let's perform a final consistency check across all updated functions:

Also applies to: 189-189

✅ Verification successful

Documentation changes are consistently applied across all related functions

The promotion of Combinations signature to official status is uniformly documented with version 4.0.0 across all related functions, including A*, Dijkstra, and Max Flow families.

🏁 Scripts executed

The following scripts were executed for the analysis:

Script:

#!/bin/bash
# Description: Final consistency check across all updated functions
# Verify consistent versioning and promotion language
rg -l "Combinations signature promoted to official" --type rst | xargs rg -l "Version 4\.0\.0"

Length of output: 477

doc/withPoints/pgr_withPointsDD.rst (1)

11-14: Documentation updates are accurate and well-structured.

The changes correctly reflect the promotion of the function to official status in version 4.0.0, with appropriate updates to index entries and version information.

Also applies to: 25-28

doc/withPoints/pgr_withPoints.rst (1)

26-29: Documentation updates maintain consistency across sections.

The changes appropriately reflect the function's promotion to official status, with consistent updates across version information and all index entries.

Also applies to: 92-92, 113-113, 135-135, 156-156, 178-178

doc/ksp/pgr_KSP.rst (1)

23-26: Documentation updates correctly reflect signature promotions.

The changes appropriately document the promotion of all signatures to official status in version 4.0.0, with consistent updates to index entries.

Also applies to: 100-100, 121-121, 142-142, 163-163

doc/trsp/pgr_trspVia_withPoints.rst (1)

27-30: Documentation updates align with function promotion.

The changes correctly document the function's promotion to official status in version 4.0.0, with appropriate updates to version information and index entries.

Also applies to: 68-68

doc/trsp/pgr_trsp_withPoints.rst (1)

26-29: Documentation updates maintain consistency with related functions.

The changes appropriately reflect the function's promotion to official status, with consistent updates across version information and index entries, aligning with the updates to related functions.

Also applies to: 88-88, 110-110, 131-131, 152-152, 174-174

doc/dijkstra/pgr_dijkstra.rst (2)

24-27: LGTM! Version information is correctly updated.

The version information and promotion of the Combinations signature is properly documented in the Availability section.

---

182-182: LGTM! Combinations index entry is correctly updated.

The index entry for Combinations is properly updated, removing any "Proposed" labels to reflect its official status.

NEWS.md (4)

11-14: LGTM! Release notes header and link are properly formatted.

The link to view closed issues and pull requests is correctly formatted and follows the established pattern.

🧰 Tools

🪛 Markdownlint (0.37.0)

12-12: null
Spaces inside link text

(MD039, no-space-in-links)

🪛 LanguageTool

[uncategorized] ~11-~11: Possible missing comma found.
Context: ...l issues & pull requests closed by this release see the [Git closed milestone for 4.0.0...

(AI_HYDRA_LEO_MISSING_COMMA)

---

15-27: LGTM! Functions promoted to official are well documented.

The list of functions promoted to official status is comprehensive and properly formatted.

🧰 Tools

🪛 Markdownlint (0.37.0)

15-15: null
Emphasis used instead of a heading

(MD036, no-emphasis-as-heading)

---

28-43: LGTM! Signatures promoted to official are well documented.

The list of signatures promoted to official status is comprehensive and properly formatted.

🧰 Tools

🪛 Markdownlint (0.37.0)

28-28: null
Emphasis used instead of a heading

(MD036, no-emphasis-as-heading)

---

44-44: 🧹 Nitpick (assertive)

Consider adding a line break before the section header.

There are multiple consecutive blank lines before this section header.

Apply this diff to fix the formatting:

-

**Removal of deprecated functions and signatures**
+**Removal of deprecated functions and signatures**

Likely invalid or redundant comment.

🧰 Tools

🪛 Markdownlint (0.37.0)

44-44: Expected: 1; Actual: 2
Multiple consecutive blank lines

(MD012, no-multiple-blanks)

doc/src/release_notes.rst (3)

42-45: LGTM! Release notes header and link are properly formatted in RST.

The link to view closed issues and pull requests is correctly formatted using RST syntax.

---

46-58: LGTM! Functions promoted to official are well documented in RST.

The list of functions promoted to official status is comprehensive and properly formatted using RST syntax.

---

59-74: LGTM! Signatures promoted to official are well documented in RST.

The list of signatures promoted to official status is comprehensive and properly formatted using RST syntax.

---

🪧 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.
  • Generate unit testing code for this file.
  • 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 generate unit testing code for this file.
  • @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 generate unit testing code.
  • @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.

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. (Beta)
• @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 review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.