feat: add Practice section (P1 Quick Start, P2 Tutorial) - #13
Conversation
Add two new practice documents in English: - P1: Quick Start guide using be-framework/app skeleton - P2: Emergency Triage tutorial demonstrating Be Framework paradigm The tutorial showcases: - Domain ontology via semantic variables - Metamorphosis pattern (Input → Being → Final) - First-class citizen treatment of domain logic (JTASProtocol) - Type-driven branching with $being property
|
Warning Rate limit exceeded@koriym has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 19 minutes and 30 seconds before requesting another review. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📒 Files selected for processing (3)
📝 WalkthroughWalkthroughAdds six new documentation files (English and Japanese getting-started and tutorial pages, plus two top-level overview files) that introduce the Be Framework metamorphosis pattern with runnable PHP examples, a triage tutorial, project structure, and conceptual walkthroughs. Changes
Sequence Diagram(s)(omitted — documentation additions only) Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. 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 |
Pull Request Review: Practice Section (P1 Quick Start, P2 Tutorial)SummaryThis PR adds valuable practical content to the Be Framework documentation with a Quick Start guide (P1) and an Emergency Triage tutorial (P2). The additions are well-written and pedagogically sound, demonstrating the framework's philosophy through concrete examples. ✅ Strengths1. Excellent Pedagogical Progression
2. Strong Consistency with Framework Philosophy
3. Well-Structured Code Examples
4. Cross-referencing
🔍 Issues & RecommendationsCRITICAL: Missing Navigation UpdatesIssue: The PR description mentions "Navigation update will follow in a separate PR", but users won't be able to discover these new pages through the site navigation until that happens. Recommendation: Either:
The navigation is auto-generated from Jekyll frontmatter in Code Quality & Best Practices1. Inconsistent Cross-link Formatting (Minor)Issue: Mixed link formats in the documents:
Recommendation: Stick with the simpler 2. Tutorial Length (Observation)Observation: P2 is 394 lines - significantly longer than typical manual sections. Analysis: This is actually appropriate for a tutorial vs. a reference chapter. The length is justified by:
No action needed - but consider adding a table of contents at the top for easier navigation if you revise. 3. Code Example Completeness (Enhancement Opportunity)P1 Example (line 28-36): composer installIssue: The example assumes users successfully cloned and initialized the repo, but doesn't show how to verify the installation succeeded. Suggestion: Add a verification step: composer install
composer check # or whatever verification command exists4. Error Handling Example (Minor)P2 lines 298-307: Exception handling example shows the right approach, but could be enhanced: try {
$becoming($invalid);
} catch (SemanticVariableException $e) {
echo $e->getErrors()->getMessages('en')[0];
}Suggestion: Show what a proper error response might look like in production (HTTP response, logging, etc.), or clarify this is just for demonstration. Content & Technical Accuracy5. Medical Accuracy (Double-check)P2 Semantic Validation (lines 39-48, 61-70):
Question: Are these ranges medically accurate for "lethal" thresholds?
Recommendation: Either:
This doesn't affect the tutorial's pedagogical value, but accuracy matters for credibility. 6. JTAS Protocol Implementation (Minor)P2 lines 107-113: public function assess(float $bodyTemperature, int $heartRate): string
{
if ($bodyTemperature >= 39.0 || $heartRate >= 120) {
return 'emergency';
}
return 'observation';
}Observation: Real JTAS has 5 levels (not 2), and the criteria shown are oversimplified. This is fine - it's a tutorial, not a medical system. Consider adding: /**
* Simplified JTAS implementation for tutorial purposes.
* Real JTAS protocol has 5 levels with more complex criteria.
*/7. Namespace ConsistencyP1 line 110: $becoming = new Becoming($injector, __NAMESPACE__ . '\\Semantic');P2 line 267: $becoming = new Becoming($injector, 'Be\\App\\Semantic');Issue: Inconsistent namespace handling between examples. Recommendation: Use the same approach in both:
Prefer the Documentation Structure8. Missing Prerequisites Section in P2P1 has: Clear Requirements section (lines 12-16) P2 lacks: Prerequisites - readers jumping directly to P2 won't know they need to complete P1 first. Suggestion: Add at the top of P2: ## Prerequisites
- Complete [P1: Getting Started](./P1-getting-started.html)
- PHP 8.4+
- Basic understanding of Be Framework philosophy ([Overview](./01-overview.html))Performance Considerations9. No Performance Issues IdentifiedThe code examples demonstrate framework usage correctly. Since this is a documentation site (static Jekyll), and the examples are illustrative code (not executed), there are no performance concerns. The generated static site should remain fast. Security Concerns10. No Security IssuesThe examples properly demonstrate:
The tutorial encourages security-by-design through semantic validation, which is excellent. Test Coverage11. No Tests NeededThis is documentation content, not application code. However: Suggestion: Consider adding a CI check that:
This would catch broken links like 📋 Comparison with Existing PatternsFrontmatter ✅Consistent with existing pages: layout: docs-en
title: "P1. Getting Started"
category: Manual
permalink: /manuals/1.0/en/P1-getting-started.htmlPhilosophical Quotes ✅Both pages include opening quotes, matching the style of other chapters:
Code Block Formatting ✅Consistent use of:
Table Usage ✅P2 uses tables effectively (lines 143-147, 365-372), consistent with Chapter 7. 🎯 Summary & RecommendationsMust Fix Before Merge
Should Fix (High Value)
Nice to Have (Lower Priority)
Optional Enhancements
Final VerdictRecommendation: APPROVE with minor revisions This PR significantly enhances the documentation by bridging the gap between philosophy and practice. The code quality is high, the examples are realistic and pedagogically sound, and the content aligns well with the framework's philosophy. The main blocker is the navigation update - once that's addressed, this will be a valuable addition to the Be Framework documentation. Great work! The Emergency Triage example is particularly effective at demonstrating being-oriented programming in a way that feels natural rather than forced. Reviewed by: Claude (Sonnet 4.5) |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
manuals/1.0/en/P1-getting-started.md (1)
42-42: Add language identifiers to code blocks for ASCII diagrams.Two fenced code blocks showing structural diagrams lack language specifications. While these are intentional ASCII art rather than executable code, adding a language identifier (e.g.,
```textor blank) would satisfy markdown linting requirements.🔎 Proposed fixes
## Project Structure - ``` + ```text src/ ├── Input/
HelloInput('World') ↓ Becoming executes</details> Also applies to: 118-118 </blockquote></details> <details> <summary>manuals/1.0/en/P2-tutorial.md (1)</summary><blockquote> `18-18`: **Add language identifiers to code blocks for ASCII diagrams.** Three fenced code blocks displaying flow and structure diagrams lack language specifications. While these are intentional ASCII visualizations rather than executable code, adding a language identifier (e.g., ` ```text `) would satisfy markdown linting requirements. <details> <summary>🔎 Proposed fixes</summary> ```diff ## The Metamorphosis - ``` + ```text PatientArrival (raw vital signs) ↓ JTAS Protocol assesses## The Complete Flow - ``` + ```text PatientArrival(39.5°C, 90 bpm) ↓ #[Be([TriageAssessment::class])]## Project Structure - ``` + ```text src/ ├── Being/Also applies to: 282-282, 346-346
📜 Review details
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
manuals/1.0/en/P1-getting-started.mdmanuals/1.0/en/P2-tutorial.md
🧰 Additional context used
📓 Path-based instructions (1)
manuals/1.0/@(en|ja)/**/*.md
📄 CodeRabbit inference engine (CLAUDE.md)
manuals/1.0/@(en|ja)/**/*.md: Place new manual pages as Markdown under manuals/1.0/en/ or manuals/1.0/ja/
Manual pages must include correct layout in frontmatter: docs-en for English, docs-ja for Japanese
Use .html permalinks for cross-links in content (avoid linking to .md)
Files:
manuals/1.0/en/P2-tutorial.mdmanuals/1.0/en/P1-getting-started.md
🪛 markdownlint-cli2 (0.18.1)
manuals/1.0/en/P2-tutorial.md
18-18: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
282-282: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
346-346: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
manuals/1.0/en/P1-getting-started.md
42-42: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
118-118: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: claude-review
🔇 Additional comments (5)
manuals/1.0/en/P1-getting-started.md (2)
1-6: Frontmatter and permalink structure is correct.Layout matches coding guidelines (docs-en for English), and .html permalink format is properly applied.
154-159: Cross-links correctly use .html format.All internal references follow the guideline to use .html permalinks (not .md). Verification confirms that all referenced documentation pages exist in the repository:
- P2-tutorial.md (links as ./P2-tutorial.html)
- 02-input-classes.md (links as ./02-input-classes.html)
- 04-final-objects.md (links as ./04-final-objects.html)
- 06-semantic-variables.md (links as ./06-semantic-variables.html)
manuals/1.0/en/P2-tutorial.md (3)
1-6: Frontmatter and permalink structure is correct.Layout matches coding guidelines (docs-en for English), and .html permalink format is properly applied.
1-394: Comprehensive and well-structured tutorial demonstrating Be Framework paradigm.The document effectively teaches core concepts through a realistic domain example (emergency triage). The pedagogical progression is clear: ontology definition → exception handling → reason/protocol → input/destiny markers → being class → final classes → execution. The comparison of traditional vs. Be Framework approaches (lines 313–343) and the cross-domain metamorphosis table (lines 380–387) effectively reinforce the philosophical underpinnings.
The tutorial complements P1-getting-started.md well, providing a more complex example that builds on foundational concepts introduced in P1.
71-71: Cross-links correctly use .html format throughout the document.All internal references follow the guideline to use .html permalinks (not .md). Referenced documentation pages exist as Markdown source files that Jekyll will build to .html, making the permalink targets accessible on the published site. Lines 71, 392-394 all properly reference:
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Fix all issues with AI agents
In @manuals/1.0/en/getting-started.md:
- Line 154: Update the broken cross-reference in the markdown by replacing the
old link target "./P2-tutorial.html" with the refactored filename
"./tutorial.html" in the "Ready for a more complete example..." line inside
getting-started.md so the "Continue to [Tutorial](...)" link points to the
correct tutorial file.
- Around line 118-123: The fenced code block showing the transformation diagram
(starting with HelloInput('World') and showing Becoming executes → Hello (with
Greeting injected) → "Hello World") lacks a language identifier; update the
opening triple-backtick to include "text" (i.e., ```text) so the block is
recognized as plain text and satisfies MD040 linting.
In @manuals/1.0/en/tutorial.md:
- Around line 282-293: The fenced code block containing the flow diagram
(starting with "PatientArrival(39.5°C, 90 bpm)" and showing TriageAssessment →
EmergencyCase) lacks a language identifier; add a language tag (e.g., "text")
immediately after the opening backticks (so the block reads ```text) to satisfy
MD040 and improve rendering while leaving the diagram content and closing
backticks unchanged.
📜 Review details
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
manuals/1.0/en/getting-started.mdmanuals/1.0/en/tutorial.md
🧰 Additional context used
📓 Path-based instructions (1)
manuals/1.0/@(en|ja)/**/*.md
📄 CodeRabbit inference engine (CLAUDE.md)
manuals/1.0/@(en|ja)/**/*.md: Place new manual pages as Markdown under manuals/1.0/en/ or manuals/1.0/ja/
Manual pages must include correct layout in frontmatter: docs-en for English, docs-ja for Japanese
Use .html permalinks for cross-links in content (avoid linking to .md)
Files:
manuals/1.0/en/getting-started.mdmanuals/1.0/en/tutorial.md
🪛 markdownlint-cli2 (0.18.1)
manuals/1.0/en/getting-started.md
42-42: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
118-118: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
manuals/1.0/en/tutorial.md
18-18: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
282-282: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
346-346: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (3)
manuals/1.0/en/tutorial.md (2)
346-366: Specify language for project structure code block (MD040).Add a language identifier to improve rendering and pass linting.
🔎 Proposed fix
-``` +```text src/ ├── Being/ │ └── TriageAssessment.php # Intermediate stage ├── Exception/ │ └── LethalVitalException.php ├── Input/ │ └── PatientArrival.php # Raw data ├── Module/ │ └── AppModule.php # DI configuration ├── Final/ │ ├── EmergencyCase.php # Final form: emergency │ └── ObservationCase.php # Final form: observation ├── Reason/ │ ├── Emergency.php # Destiny marker │ ├── JTASProtocol.php # Transcendent wisdom │ └── Observation.php # Destiny marker └── Semantic/ ├── BodyTemperature.php # What CAN exist └── HeartRate.php -``` +```⛔ Skipped due to learnings
Learnt from: koriym Repo: be-framework/be-framework.github.io PR: 10 File: concept/dev-docs/PR_DESCRIPTION.md:94-94 Timestamp: 2025-12-16T11:23:45.795Z Learning: In this repository, fenced code blocks without language identifiers are acceptable and should not be flagged during review.
18-24: Specify language for metamorphosis diagram code block (MD040).Add a language identifier to improve rendering and pass linting.
🔎 Proposed fix
-``` +```text PatientArrival (raw vital signs) ↓ JTAS Protocol assesses TriageAssessment (the chrysalis stage) ↓ Destiny is determined EmergencyCase or ObservationCase (final existence) -``` +```⛔ Skipped due to learnings
Learnt from: koriym Repo: be-framework/be-framework.github.io PR: 10 File: concept/dev-docs/PR_DESCRIPTION.md:94-94 Timestamp: 2025-12-16T11:23:45.795Z Learning: In this repository, fenced code blocks without language identifiers are acceptable and should not be flagged during review.manuals/1.0/en/getting-started.md (1)
42-56: Specify language for fenced code block (MD040).Add a language identifier to improve syntax highlighting and pass linting.
🔎 Proposed fix
-``` +```text src/ ├── Input/ │ └── HelloInput.php # Starting point ├── Final/ │ └── Hello.php # Destination ├── Reason/ │ └── Greeting.php # Transcendent capability ├── Semantic/ │ └── Name.php # Validation rules ├── Exception/ │ └── EmptyNameException.php └── Module/ └── AppModule.php # DI configuration -``` +```⛔ Skipped due to learnings
Learnt from: koriym Repo: be-framework/be-framework.github.io PR: 10 File: concept/dev-docs/PR_DESCRIPTION.md:94-94 Timestamp: 2025-12-16T11:23:45.795Z Learning: In this repository, fenced code blocks without language identifiers are acceptable and should not be flagged during review.
- Add Prerequisites section to tutorial - Fix broken link (P2-tutorial.html → tutorial.html) - Unify namespace style across examples
|
@CodeRabbit Re: MD040 code block language identifiers - Per repository learning, fenced code blocks without language identifiers are acceptable here. The broken link issue has been fixed in dceb9a1. |
|
Tip For best results, initiate chat on the files or code changes. @koriym, thank you for the clarification! I've confirmed that the repository learning about fenced code blocks without language identifiers is already in my knowledge base, and I'll respect that preference going forward. I also appreciate you fixing the broken link in dceb9a1. The changes look good! 🧠 Learnings used |
|
Thanks for the thorough review. @claude @coderabbitai Addressed:
Will address in follow-up PR:
Not addressing:
|
|
Tip For best results, initiate chat on the files or code changes. @koriym, excellent work! Thank you for the comprehensive status update. I'm glad to see you've addressed the key feedback: ✅ Prerequisites section - helps readers understand requirements upfront Deferred items: Navigation integration in a follow-up PR is perfectly reasonable and keeps this PR focused. Non-addressed items: Your rationale is sound:
The tutorial effectively demonstrates Be Framework's core concepts (domain ontology, metamorphosis, first-class domain logic) with a clear, traceable example. Great work on the documentation! 🎉 🧠 Learnings usedIf you found this review helpful, would you consider giving us a shout-out on X? Thank you for using CodeRabbit! |
|
@coderabbitai Any other concerns? Ready to merge? |
|
Tip For best results, initiate chat on the files or code changes. @koriym, no remaining concerns! 🎉 You've addressed all the key feedback:
The practice documents effectively demonstrate Be Framework's core concepts (metamorphosis pattern, domain ontology, type-driven branching) with clear, runnable examples. Deferring navigation integration to a follow-up PR keeps this focused. Ready to merge! ✅ 🧠 Learnings used |
366b472 to
70f3d6e
Compare
1 participant
Summary
Key concepts demonstrated in Tutorial
Note
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.