docs: README rewrite (shipping behavior only) + pgx adoption feedback on the roadmap#32
Merged
Conversation
…pping features) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> # Conflicts: # CHANGELOG.md # ROADMAP.md
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Full rewrite (861 → ~380 lines): honest positioning (embedded declarative Petri-net library, not a Temporal competitor), an explicit is-this-the- right-tool section (including when NOT to use it), a quick start extracted and verified to compile AND run verbatim (prints [review] as its comment claims), the model in sixty seconds with the renderer's own diagram, a feature tour where every claim is shipped and linked to its guide, the persistence contract with a bring-your-own-driver section (the tx-any design: pgx-native backends hand effects a real pgx.Tx, storagetest proves conformance), docs and examples tables, and the boundaries summary. Still pre-1.0: the beta status note stays (this is NOT the v1.0 gate closing — other gate criteria remain open). Go version badge fixed to 1.25+ (go.mod); retired Go Report Card badge already replaced earlier. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> # Conflicts: # CHANGELOG.md # README.md
An external evaluation declined adoption on two grounds; both are now recorded where they act: 1. "The library's tx wouldn't be our tx" (pgx-native + sqlc stack, hard same-transaction rule for audit/outbox). Half-right: the shipped backends speak database/sql, but the CONTRACT doesn't — TxSideEffect receives tx as `any` precisely so a custom backend hands effects a pgx.Tx, and storagetest proves conformance. ROADMAP gains an adoption-driven `contrib/pgx` candidate so evaluators don't have to build that backend to find out; the README's new bring-your-own-driver section documents the extension point today. 2. Flat status-column domain → Petri net oversized. Correct per our own boundaries; the README's "Is this the right tool?" section now says it up front so the next evaluation reads it from us first. Also: the v1.0-gate README-rewrite line updated to note the rewrite landed early while THE GATE STAYS OPEN (still pre-1.0). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
Warning Review limit reached
Next review available in: 51 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (4)
WalkthroughChangesWorkflow platform and examples
Estimated code review effort: 4 (Complex) | ~60 minutes Sequence Diagram(s)sequenceDiagram
participant Workflow
participant Observer
participant OTelInstrumentation
participant TelemetryProviders
Workflow->>Observer: dispatch before/after/rejected event
Observer->>OTelInstrumentation: invoke panic-safe callback
OTelInstrumentation->>TelemetryProviders: record span or outcome metric
Possibly related PRs
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (1)
examples/expense_approval/flows_test.go (1)
340-340: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winExercise a non-default diagram direction.
The test now verifies only the TD default, so the endpoint could ignore its
dirquery parameter without detection. Add a request such as/diagrams?dir=LRand assertflowchart LR.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@examples/expense_approval/flows_test.go` at line 340, Extend the diagram endpoint test around the existing “flowchart TD” assertion to issue a request with dir=LR and verify the response contains “flowchart LR”. Keep the default TD coverage and use the same request/assertion helpers already used in the test.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@examples/advanced_workflow/README.md`:
- Line 80: Correct the guard labels in the README entries around the
approve-design flow and the corresponding entry near line 90 by changing each
malformed `#39`; apostrophe entity to the proper &`#39`; form, preserving the
surrounding label expressions and quoted context keys.
In `@examples/advanced_workflow/workflow.yaml`:
- Line 121: Move the person classification from the deployment_ready definition
to the mark_deployment_ready definition in the workflow configuration. Remove
diagram_class: person from deployment_ready and assign it to
mark_deployment_ready so the generated diagram classifies the human decision
task correctly.
In `@examples/expense_approval/otel.go`:
- Around line 36-68: Update the provider initialization flow around the tracer
provider, meter provider, and otelworkflow.Instrument calls so every later
initialization failure shuts down all providers created so far before returning.
Delay otel.SetTracerProvider and otel.SetMeterProvider until instrumentation
succeeds, preventing globals from referencing providers that cannot be closed;
preserve the existing successful shutdown callback for both providers.
---
Nitpick comments:
In `@examples/expense_approval/flows_test.go`:
- Line 340: Extend the diagram endpoint test around the existing “flowchart TD”
assertion to issue a request with dir=LR and verify the response contains
“flowchart LR”. Keep the default TD coverage and use the same request/assertion
helpers already used in the test.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 8a75f741-8ed9-4155-a863-9ff1d0499fdb
⛔ Files ignored due to path filters (2)
contrib/otel/go.sumis excluded by!**/*.sumexamples/expense_approval/go.sumis excluded by!**/*.sum
📒 Files selected for processing (42)
.github/workflows/ci.yml.gitignoreCHANGELOG.mdREADME.mdROADMAP.mdcontrib/otel/README.mdcontrib/otel/go.modcontrib/otel/otel.gocontrib/otel/otel_test.godefinition.goevent.goexamples/advanced_workflow/OR_SEMANTICS_BEST_PRACTICES.mdexamples/advanced_workflow/README.mdexamples/advanced_workflow/go.modexamples/advanced_workflow/main.goexamples/advanced_workflow/templates/diagram.htmlexamples/advanced_workflow/templates/project.htmlexamples/advanced_workflow/workflow.yamlexamples/advanced_workflow/workflow_yaml_test.goexamples/expense_approval/README.mdexamples/expense_approval/app.goexamples/expense_approval/flows_test.goexamples/expense_approval/go.modexamples/expense_approval/main.goexamples/expense_approval/otel.goexamples/expense_approval/payment_migration_test.goexamples/expense_approval/server.goexamples/expense_approval/templates/batch.htmlexamples/expense_approval/templates/detail.htmlexamples/expense_approval/templates/diagrams.htmlexamples/expense_approval/templates/layout.htmlexamples/website_workflow/main.goexamples/website_workflow/templates/diagram.htmllisteners.gomanager.gomermaid.goobserver_test.gotoken_firing.goworkflow.goworkflow_test.goworkflowtest/workflowtest.goworkflowtest/workflowtest_test.go
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> # Conflicts: # CHANGELOG.md
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> # Conflicts: # CHANGELOG.md
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #32 +/- ##
==========================================
+ Coverage 81.20% 81.70% +0.50%
==========================================
Files 30 31 +1
Lines 3128 3252 +124
==========================================
+ Hits 2540 2657 +117
- Misses 368 374 +6
- Partials 220 221 +1
🚀 New features to boost your workflow:
|
- otel.go: shut down already-created providers on later init failures, and set OTel globals only after full success (no leak on partial init). - advanced_workflow: move diagram_class: person from the deployment_ready place to the mark_deployment_ready transition (the human decision), and regenerate the README diagram to match (now shows the START marker and the person-classed decision, consistent with the app's rendering). Skipped the '#39;' guard-label finding: that is Mermaid's own numeric entity convention (# without &), used deliberately by escapeMermaidLabel alongside #58;/#34;/#60; — it renders as an apostrophe, not literal text. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
# Conflicts: # CHANGELOG.md # ROADMAP.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The README rewrite (the item originally deferred to the v1.0 gate, landed early by request — the gate itself stays open, the beta status note remains):
[review]exactly as its comment claimstx anycontract means a custom backend hands transactional side effects its own transaction type (e.g.pgx.Tx), validated bystoragetest.RunAdoption feedback recorded — an external evaluation declined adoption ("the library's tx wouldn't be our tx"; pgx-native + sqlc stack with a hard same-transaction rule). The ROADMAP gains an adoption-driven
contrib/pgxcandidate (native pgxpool backend, effects receivingpgx.Tx, full conformance against real Postgres) so the next evaluator doesn't have to build that backend to find out; the evaluation's second point (Petri net oversized for a flat status column) is a correct application of our own boundaries and the README now says so first.Checklist
replaceto this branch)CHANGELOG.mdupdated under [Unreleased]🤖 Generated with Claude Code
Summary by CodeRabbit
New Features
Documentation
Bug Fixes