docs: add repository method conventions to knowledge base#24443
Merged
Conversation
- Add comprehensive repository method naming conventions - Include examples for method naming patterns - Document separation of concerns between repositories and services - Emphasize reusability and generic method naming Co-Authored-By: hariom@cal.com <hariombalhara@gmail.com>
Contributor
🤖 Devin AI EngineerI'll be helping with this pull request! Here's what you should know: ✅ I will automatically:
Note: I can only respond to comments from users who have write access to this repository. ⚙️ Control Options:
|
keithwillcode
added
core
Contributor
WalkthroughA new "Repository Method Conventions" documentation block was added to .agents/knowledge-base.md. It outlines naming rules, relation fetching semantics (including explicit include-like patterns), guidance on generic/reusable method design, and separation of concerns (repositories limited to data access, business logic in services). Concrete code examples are provided (e.g., findById, findByIdIncludeHosts, findByUserIdIncludeAttendees). The same section appears twice in the file, resulting in duplicated content. No changes to exported or public entities are present. Pre-merge checks and finishing touches✅ Passed checks (3 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}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
.agents/knowledge-base.md(1 hunks)
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-07-28T11:50:23.946Z
Learnt from: CR
PR: calcom/cal.com#0
File: .cursor/rules/review.mdc:0-0
Timestamp: 2025-07-28T11:50:23.946Z
Learning: Applies to **/*Repository.ts : Repository files must include `Repository` suffix, prefix with technology if applicable (e.g., `PrismaAppRepository.ts`), and use PascalCase matching the exported class
Applied to files:
.agents/knowledge-base.md
🪛 markdownlint-cli2 (0.18.1)
.agents/knowledge-base.md
315-315: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
393-393: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
447-447: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
Comment on lines
+315
to
+447
| **1. Don't include the repository's entity name in method names** | ||
|
|
||
| Method names should be concise and avoid redundancy since the repository class name already indicates the entity type. | ||
|
|
||
| ```typescript | ||
| // ✅ Good - Concise method names | ||
| class BookingRepository { | ||
| findById(id: string) { ... } | ||
| findByUserId(userId: string) { ... } | ||
| create(data: BookingCreateInput) { ... } | ||
| delete(id: string) { ... } | ||
| } | ||
|
|
||
| // ❌ Bad - Redundant entity name in methods | ||
| class BookingRepository { | ||
| findBookingById(id: string) { ... } | ||
| findBookingByUserId(userId: string) { ... } | ||
| createBooking(data: BookingCreateInput) { ... } | ||
| deleteBooking(id: string) { ... } | ||
| } | ||
| ``` | ||
|
|
||
| **2. Use `include` or similar keywords for methods that fetch relational data** | ||
|
|
||
| When a method retrieves additional related entities, make this explicit in the method name using keywords like `include`, `with`, or `andRelations`. | ||
|
|
||
| ```typescript | ||
| // ✅ Good - Clear indication of included relations | ||
| class EventTypeRepository { | ||
| findById(id: string) { | ||
| return prisma.eventType.findUnique({ | ||
| where: { id }, | ||
| }); | ||
| } | ||
|
|
||
| findByIdIncludeHosts(id: string) { | ||
| return prisma.eventType.findUnique({ | ||
| where: { id }, | ||
| include: { | ||
| hosts: true, | ||
| }, | ||
| }); | ||
| } | ||
|
|
||
| findByIdIncludeHostsAndSchedule(id: string) { | ||
| return prisma.eventType.findUnique({ | ||
| where: { id }, | ||
| include: { | ||
| hosts: true, | ||
| schedule: true, | ||
| }, | ||
| }); | ||
| } | ||
| } | ||
|
|
||
| // ❌ Bad - Unclear what data is included | ||
| class EventTypeRepository { | ||
| findById(id: string) { | ||
| return prisma.eventType.findUnique({ | ||
| where: { id }, | ||
| include: { | ||
| hosts: true, | ||
| schedule: true, | ||
| }, | ||
| }); | ||
| } | ||
|
|
||
| findByIdForReporting(id: string) { | ||
| return prisma.eventType.findUnique({ | ||
| where: { id }, | ||
| include: { | ||
| hosts: true, | ||
| }, | ||
| }); | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| **3. Keep methods generic and reusable - avoid use-case-specific names** | ||
|
|
||
| Repository methods should be general-purpose and describe what data they return, not how or where it's used. This promotes code reuse across different features. | ||
|
|
||
| ```typescript | ||
| // ✅ Good - Generic, reusable methods | ||
| class BookingRepository { | ||
| findByUserIdIncludeAttendees(userId: string) { | ||
| return prisma.booking.findMany({ | ||
| where: { userId }, | ||
| include: { | ||
| attendees: true, | ||
| }, | ||
| }); | ||
| } | ||
|
|
||
| findByDateRangeIncludeEventType(startDate: Date, endDate: Date) { | ||
| return prisma.booking.findMany({ | ||
| where: { | ||
| startTime: { gte: startDate }, | ||
| endTime: { lte: endDate }, | ||
| }, | ||
| include: { | ||
| eventType: true, | ||
| }, | ||
| }); | ||
| } | ||
| } | ||
|
|
||
| // ❌ Bad - Use-case-specific method names | ||
| class BookingRepository { | ||
| findBookingsForReporting(userId: string) { | ||
| return prisma.booking.findMany({ | ||
| where: { userId }, | ||
| include: { | ||
| attendees: true, | ||
| }, | ||
| }); | ||
| } | ||
|
|
||
| findBookingsForDashboard(startDate: Date, endDate: Date) { | ||
| return prisma.booking.findMany({ | ||
| where: { | ||
| startTime: { gte: startDate }, | ||
| endTime: { lte: endDate }, | ||
| }, | ||
| include: { | ||
| eventType: true, | ||
| }, | ||
| }); | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| **4. No business logic in repositories** |
Contributor
There was a problem hiding this comment.
Fix markdownlint MD036 violations in numbered rules.
markdownlint is flagging the bolded rule titles (**1. ...**, **2. ...**, etc.) as “emphasis used instead of a heading,” which will keep the PR failing lint. Please convert them into plain numbered list items (or actual subheadings) so the section passes MD036.
-**1. Don't include the repository's entity name in method names**
+1. Don't include the repository's entity name in method names
…
-**2. Use `include` or similar keywords for methods that fetch relational data**
+2. Use `include` or similar keywords for methods that fetch relational data
…
-**3. Keep methods generic and reusable - avoid use-case-specific names**
+3. Keep methods generic and reusable - avoid use-case-specific names
…
-**4. No business logic in repositories**
+4. No business logic in repositories📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| **1. Don't include the repository's entity name in method names** | |
| Method names should be concise and avoid redundancy since the repository class name already indicates the entity type. | |
| ```typescript | |
| // ✅ Good - Concise method names | |
| class BookingRepository { | |
| findById(id: string) { ... } | |
| findByUserId(userId: string) { ... } | |
| create(data: BookingCreateInput) { ... } | |
| delete(id: string) { ... } | |
| } | |
| // ❌ Bad - Redundant entity name in methods | |
| class BookingRepository { | |
| findBookingById(id: string) { ... } | |
| findBookingByUserId(userId: string) { ... } | |
| createBooking(data: BookingCreateInput) { ... } | |
| deleteBooking(id: string) { ... } | |
| } | |
| ``` | |
| **2. Use `include` or similar keywords for methods that fetch relational data** | |
| When a method retrieves additional related entities, make this explicit in the method name using keywords like `include`, `with`, or `andRelations`. | |
| ```typescript | |
| // ✅ Good - Clear indication of included relations | |
| class EventTypeRepository { | |
| findById(id: string) { | |
| return prisma.eventType.findUnique({ | |
| where: { id }, | |
| }); | |
| } | |
| findByIdIncludeHosts(id: string) { | |
| return prisma.eventType.findUnique({ | |
| where: { id }, | |
| include: { | |
| hosts: true, | |
| }, | |
| }); | |
| } | |
| findByIdIncludeHostsAndSchedule(id: string) { | |
| return prisma.eventType.findUnique({ | |
| where: { id }, | |
| include: { | |
| hosts: true, | |
| schedule: true, | |
| }, | |
| }); | |
| } | |
| } | |
| // ❌ Bad - Unclear what data is included | |
| class EventTypeRepository { | |
| findById(id: string) { | |
| return prisma.eventType.findUnique({ | |
| where: { id }, | |
| include: { | |
| hosts: true, | |
| schedule: true, | |
| }, | |
| }); | |
| } | |
| findByIdForReporting(id: string) { | |
| return prisma.eventType.findUnique({ | |
| where: { id }, | |
| include: { | |
| hosts: true, | |
| }, | |
| }); | |
| } | |
| } | |
| ``` | |
| **3. Keep methods generic and reusable - avoid use-case-specific names** | |
| Repository methods should be general-purpose and describe what data they return, not how or where it's used. This promotes code reuse across different features. | |
| ```typescript | |
| // ✅ Good - Generic, reusable methods | |
| class BookingRepository { | |
| findByUserIdIncludeAttendees(userId: string) { | |
| return prisma.booking.findMany({ | |
| where: { userId }, | |
| include: { | |
| attendees: true, | |
| }, | |
| }); | |
| } | |
| findByDateRangeIncludeEventType(startDate: Date, endDate: Date) { | |
| return prisma.booking.findMany({ | |
| where: { | |
| startTime: { gte: startDate }, | |
| endTime: { lte: endDate }, | |
| }, | |
| include: { | |
| eventType: true, | |
| }, | |
| }); | |
| } | |
| } | |
| // ❌ Bad - Use-case-specific method names | |
| class BookingRepository { | |
| findBookingsForReporting(userId: string) { | |
| return prisma.booking.findMany({ | |
| where: { userId }, | |
| include: { | |
| attendees: true, | |
| }, | |
| }); | |
| } | |
| findBookingsForDashboard(startDate: Date, endDate: Date) { | |
| return prisma.booking.findMany({ | |
| where: { | |
| startTime: { gte: startDate }, | |
| endTime: { lte: endDate }, | |
| }, | |
| include: { | |
| eventType: true, | |
| }, | |
| }); | |
| } | |
| } | |
| ``` | |
| **4. No business logic in repositories** | |
| 1. Don't include the repository's entity name in method names | |
| Method names should be concise and avoid redundancy since the repository class name already indicates the entity type. | |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
315-315: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
393-393: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
447-447: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
🤖 Prompt for AI Agents
In .agents/knowledge-base.md around lines 315 to 447 the numbered rule titles
are bolded (e.g. "**1. ...**") and trigger markdownlint MD036; remove the bold
emphasis from those numbered headings and convert them into either plain
numbered list items (e.g. "1. Don't include...") or proper Markdown subheadings
(e.g. "### Don't include...") consistently for all rules 1–4 so the emphasis is
not used in place of headings, then run markdownlint to verify the MD036
violation is resolved.
Contributor
E2E results are ready! |
|
The latest updates on your projects. Learn more about Vercel for GitHub. |
akarsh-jain-790
pushed a commit
to akarsh-jain-790/cal.com
that referenced
this pull request
Mar 8, 2026
- Add comprehensive repository method naming conventions - Include examples for method naming patterns - Document separation of concerns between repositories and services - Emphasize reusability and generic method naming Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
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
3 participants
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.
What does this PR do?
This PR adds a comprehensive "Repository Method Conventions" section to the
.agents/knowledge-base.mdfile. The conventions provide guidance on:findByIdinstead offindBookingById)include,with, orandRelationswhen fetching related data (e.g.,findByIdIncludeHosts)Each convention includes clear examples showing both good and bad patterns.
Context: These conventions were requested to establish consistency in repository patterns across the codebase.
Session URL: https://app.devin.ai/sessions/c3e3e2d687214883855cd44f4dd00953
Requested by: @hariombalhara (hariom@cal.com)
Visual Demo
N/A - Documentation only change.
Mandatory Tasks
How should this be tested?
No testing required - this is a documentation-only change. However, reviewers should:
Human Review Checklist
Important items to verify:
Checklist