Deprecate pgr_analyzeGraph #2819
Conversation
- SQL: mark function as deprecated - doc: - Migration: add migration suggestions - docqueries: - Update results adding message that is shown
WalkthroughThe changes update the pgRouting 3.8.0 documentation and SQL scripts. In the release files, functions have been promoted or deprecated (with Changes
Sequence Diagram(s)sequenceDiagram
participant U as User/Developer
participant A as pgr_analyzeGraph
participant W as Warning System
participant M as Migration Guide
U->>A: Call pgr_analyzeGraph
A->>W: Emit deprecation warning (v3.8.0)
W-->>U: Return warning message
U->>M: Consult migration guide
M-->>U: Recommend using pgr_connectedComponents, etc.
sequenceDiagram
participant Q as Query Executor
participant C as pgr_connectedComponents
participant D as pgr_degree
participant F as pgr_findCloseEdges
Q->>C: Execute components analysis (analysis1)
Q->>D: Run degree check for dead ends (analysis2)
Q->>F: Find close edges for identified dead ends (analysis3)
Poem
📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (2)
Note 🎁 Summarized by CodeRabbit FreeYour organization has reached its limit of developer seats under the Pro Plan. For new users, CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please add seats to your subscription by visiting https://app.coderabbit.ai/login.If you believe this is a mistake and have available seats, please assign one to the pull request author through the subscription management page using the link above. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
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)
Other keywords and placeholders
CodeRabbit Configuration File (
|
There was a problem hiding this comment.
Actionable comments posted: 6
📜 Review details
Configuration used: CodeRabbit UI
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (13)
NEWS.md(1 hunks)doc/metrics/pgr_degree.rst(2 hunks)doc/src/migration.rst(2 hunks)doc/src/pgRouting-concepts.rst(2 hunks)doc/src/release_notes.rst(1 hunks)doc/topology/pgr_analyzeGraph.rst(1 hunks)docqueries/src/migration.pg(1 hunks)docqueries/src/migration.result(1 hunks)docqueries/topology/analyzeGraph.result(24 hunks)docqueries/topology/nodeNetwork.result(5 hunks)locale/en/LC_MESSAGES/pgrouting_doc_strings.po(7 hunks)locale/pot/pgrouting_doc_strings.pot(7 hunks)sql/topology/analyzegraph.sql(2 hunks)
🧰 Additional context used
🧠 Learnings (5)
📓 Common learnings
Learnt from: cvvergara
PR: pgRouting/pgrouting#2744
File: doc/src/release_notes.rst:94-94
Timestamp: 2025-04-03T01:13:53.213Z
Learning: In pgRouting, changes to functions can happen at two levels:
1. SQL level - removal/addition of function signatures
2. C/C++ level - deprecation/changes to the underlying implementation
These are documented separately in the release notes.
Learnt from: cvvergara
PR: pgRouting/pgrouting#2771
File: doc/topology/pgr_degree.rst:28-35
Timestamp: 2025-04-03T01:13:53.213Z
Learning: In the pgRouting documentation, historical version notes should be retained to show the evolution of functions across different versions.
NEWS.md (1)
Learnt from: cvvergara
PR: pgRouting/pgrouting#2744
File: NEWS.md:63-63
Timestamp: 2025-04-03T01:13:53.213Z
Learning: In pgRouting's NEWS.md, the "Removal of SQL deprecated internal functions" section lists SQL signatures being removed, while "Deprecation of internal C/C++ functions" section lists the underlying C/C++ implementations being deprecated. A function can appear in both sections when its SQL signature is removed while its C/C++ implementation is deprecated.
doc/src/release_notes.rst (1)
Learnt from: cvvergara
PR: pgRouting/pgrouting#2744
File: doc/src/release_notes.rst:94-94
Timestamp: 2025-04-03T01:13:53.213Z
Learning: In pgRouting, changes to functions can happen at two levels:
1. SQL level - removal/addition of function signatures
2. C/C++ level - deprecation/changes to the underlying implementation
These are documented separately in the release notes.
locale/pot/pgrouting_doc_strings.pot (3)
undefined
<retrieved_learning>
Learnt from: cvvergara
PR: #2771
File: doc/topology/pgr_extractVertices.rst:28-35
Timestamp: 2025-04-03T01:13:53.213Z
Learning: In pgRouting documentation, historical version entries should be maintained in reverse chronological order (newest first) to provide context about the evolution of functions over time.
</retrieved_learning>
<retrieved_learning>
Learnt from: cvvergara
PR: #2744
File: NEWS.md:63-63
Timestamp: 2025-04-03T01:13:53.213Z
Learning: In pgRouting's NEWS.md, the "Removal of SQL deprecated internal functions" section lists SQL signatures being removed, while "Deprecation of internal C/C++ functions" section lists the underlying C/C++ implementations being deprecated. A function can appear in both sections when its SQL signature is removed while its C/C++ implementation is deprecated.
</retrieved_learning>
<retrieved_learning>
Learnt from: cvvergara
PR: #2744
File: doc/src/release_notes.rst:94-94
Timestamp: 2025-04-03T01:13:53.213Z
Learning: In pgRouting, changes to functions can happen at two levels:
- SQL level - removal/addition of function signatures
- C/C++ level - deprecation/changes to the underlying implementation
These are documented separately in the release notes.
</retrieved_learning>
locale/en/LC_MESSAGES/pgrouting_doc_strings.po (1)
undefined
<retrieved_learning>
Learnt from: cvvergara
PR: #2744
File: NEWS.md:63-63
Timestamp: 2025-04-03T01:13:53.213Z
Learning: In pgRouting's NEWS.md, the "Removal of SQL deprecated internal functions" section lists SQL signatures being removed, while "Deprecation of internal C/C++ functions" section lists the underlying C/C++ implementations being deprecated. A function can appear in both sections when its SQL signature is removed while its C/C++ implementation is deprecated.
</retrieved_learning>
🪛 markdownlint-cli2 (0.17.2)
NEWS.md
12-12: Spaces inside link text
null
(MD039, no-space-in-links)
⏰ Context from checks skipped due to timeout of 90000ms (1)
- GitHub Check: Codacy Static Code Analysis
🔇 Additional comments (25)
locale/en/LC_MESSAGES/pgrouting_doc_strings.po (9)
11-11: Date updated correctly.The POT-Creation-Date has been updated to reflect the current date.
3924-3929: Good addition of milestone link.The link to the closed milestone for 3.8.0 is helpful for users to track all issues and pull requests included in this release.
3934-3936: Documentation updated for promoted function.The promotion of
pgr_extractVerticesto an official function is properly documented with a reference to its issue number.
3945-3945: Function promotion correctly documented.Clear documentation of the promotion of
pgr_degreeto official status with proper issue reference.
3951-3953: Function promotion correctly documented.The promotion of
pgr_findCloseEdgesand removal of thepartialoption is properly documented.
4045-4168: Comprehensive migration guidance provided.The added migration section for
pgr_analyzeGraphis thorough and helpful. It:
- Explains what the function calculated before deprecation
- Provides clear definitions for graph components
- Offers specific alternative approaches for each feature
- Lists appropriate replacement functions with links
- Includes references to PostGIS functions for geometric operations
This is excellent practice when deprecating functionality as it gives users a clear path forward.
7876-7880: Proper deprecation marking.The function has been appropriately marked as deprecated with the version number (3.8.0) clearly indicated.
15917-15918: Documentation change noted correctly.The changes to the documentation for
pgr_degreeare properly listed.
16311-16312: Documentation updated for promoted function.The
pgr_extractVerticesfunction is properly added to what appears to be a list of documented functions.doc/src/pgRouting-concepts.rst (1)
740-751: Well-structured documentation enhancement with directivesThe addition of the disconnected graph directives (
disconnected_graph_startanddisconnected_graph_end) improves the documentation structure by clearly marking this section for reference from other documentation.This change enhances organization and will make it easier to maintain cross-references, especially for the migration guidance from the deprecated
pgr_analyzeGraphfunction.doc/metrics/pgr_degree.rst (1)
351-364: Good documentation restructuring with clear section markersThe addition of the
finding_dead_ends_startandfinding_dead_ends_enddirectives provides clear section boundaries for important functionality documentation. This section effectively explains how to identify dead ends in a graph using the newly promotedpgr_degreefunction, which is a key replacement for functionality in the deprecatedpgr_analyzeGraph.This change helps users understand the migration path and makes the documentation more modular and maintainable.
docqueries/src/migration.pg (1)
381-390: Good examples for migration from deprecated functionalityThese SQL examples clearly demonstrate how to perform graph analysis using the newer functions:
- Using
pgr_connectedComponentsto analyze graph connectivity- Using
pgr_degreeto identify dead ends (vertices with degree = 1)These examples provide excellent practical guidance for users migrating away from the deprecated
pgr_analyzeGraphfunction.doc/topology/pgr_analyzeGraph.rst (2)
23-26: Clear deprecation notice with appropriate version informationThe addition of the Version 3.8.0 entry with explicit "Deprecated function" statement clearly communicates the status change of this function to users.
This follows good practice for deprecating functionality by marking it in the specific version where deprecation occurs.
31-33: Properly structured migration guidanceThe inclusion of migration documentation via the
migration.rstfile provides users with a clear path forward. The specific markers (migrate_pgr_analyzeGraph_startandmigrate_pgr_analyzeGraph_end) ensure that only the relevant portion of the migration guidance is included.This approach helps users understand how to transition away from the deprecated function while maintaining backward compatibility for existing code.
locale/pot/pgrouting_doc_strings.pot (5)
11-11: Timestamp update looks good.This is a standard update to the POT creation date timestamp to reflect the most recent generation of this template file.
3523-3525: Documentation additions for promoted functions are appropriate.The addition of the Git milestone link and the documentation for promoting
pgr_extractVerticesto an official function (referencing issue #2772) is clear and follows the expected format for release notes.Also applies to: 3529-3529
3619-3732: Comprehensive migration guidance provided.The migration guidance for
pgr_analyzeGraphis thorough and well-structured:
- It clearly explains what the deprecated function calculated
- Provides definitions of relevant graph concepts
- Offers detailed alternative approaches for each aspect of the original function's functionality
- Suggests specific functions to use as replacements
This follows good practice for deprecating functions by giving users clear paths forward.
6865-6870: Appropriate version tagging and deprecation notice.Adding the version number (3.8.0) and explicitly marking the function as deprecated provides clear information to users about when this change occurred and the current status of the function.
This aligns with the learned practice of maintaining historical version notes to show function evolution over time.
13360-13361: Documentation reference updates are consistent.The addition of
pgr_degreeandpgr_extractVerticesto the list of functions with documentation changes is consistent with their promotion to official status mentioned earlier in the file.Also applies to: 13675-13676
sql/topology/analyzegraph.sql (1)
138-139: Appropriately added deprecation warning.The warning message is correctly implemented and will alert users that the function is deprecated while still allowing them to use it in this version. This is a good approach for a smooth transition.
docqueries/topology/nodeNetwork.result (3)
22-24: Test results correctly updated with deprecation warning.The test results now appropriately include the deprecation warning message that will be displayed to users when running the function. This ensures documentation accurately reflects actual behavior.
114-116: Consistent application of deprecation warnings.The deprecation warning is consistently applied across all instances of the function call in the test results, which is important for ensuring users are properly informed regardless of how they use the function.
167-169: Complete coverage of deprecation warnings.All variants of function calls now properly display the deprecation warning, ensuring comprehensive coverage across different usage patterns (with different parameters and WHERE clauses).
Also applies to: 190-192, 213-215
doc/src/migration.rst (1)
27-98: Well-structured documentation onpgr_analyzeGraphmigration.The migration guide provides comprehensive instructions for transitioning from the deprecated
pgr_analyzeGraphfunction. The documentation clearly explains the previous functionality, defines key terms, and provides appropriate alternative approaches using more modern functions.I especially appreciate:
- The organization into logical sections (Components, Dead ends, etc.)
- Clear examples with references to query implementations
- Helpful links to PostGIS functions for geometric and topological operations
docqueries/src/migration.result (1)
1244-1284: Good SQL examples demonstrating migration alternatives.These example queries effectively demonstrate the recommended alternatives for
pgr_analyzeGraphfunctionality:
- Using
pgr_connectedComponentsto identify graph components (replacing isolated segments counting)- Using
pgr_degreewith filtering to find nodes with degree 1 (dead ends)The query results clearly show the output format users should expect when implementing these alternative approaches.
be9e3e4 to
118857c
Compare
1c66da7 to
9c892b5
Compare
Fixes #2753
Changes proposed in this pull request:
@pgRouting/admins
Summary by CodeRabbit
New Features
Documentation
Deprecations
pgr_analyzeGraphfunction is now deprecated, with warning messages added to facilitate user transition.