Skip to content

Commit 042faa9

Browse files
tomerdbztomerdbz
committed
issue: 4480494 Add dev tooling and docs
Introduce comprehensive development tooling infrastructure to standardize and streamline development workflows across the libxlio codebase. Cursor Rules for Development Workflows: - commit-msg: Generate well-formatted commit messages - performance-issue: Investigate performance bottlenecks - solve-bug: Structured bug resolution workflow - test-plan: Comprehensive test plan generation - review-commit: Code review guidelines for commits - review-pr: Pull request review standards - research-functionality: Code exploration and documentation Project-Specific Guidelines: - coding.mdc: C++ standards for performance-critical code (naming conventions, pointer usage, cache alignment) - testing.mdc: Google Test patterns and fork-based testing (ti_N/tu_N naming, LD_PRELOAD requirements) Greptile Integration: - greptile.json: AI-powered code review automation (custom rules for core/tests/config, performance checks) These rules leverage MCP tools (Redmine, Confluence, GitHub) for context-aware assistance and integrate with existing project documentation (coding-style.md, style.conf). Benefits: - Standardized commit messages and documentation - Automated code quality checks via Greptile - Structured workflows for common development tasks - Better onboarding for new contributors - Context-aware AI assistance through Cursor rules Signed-off-by: Tomer Cabouly <[email protected]>
1 parent 8eeccc7 commit 042faa9

File tree

11 files changed

+3661
-0
lines changed

11 files changed

+3661
-0
lines changed

‎.cursor/rules/coding.mdc‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
---
2+
globs: **/*.c,**/*.cpp,**/*.h,**/*.cc
3+
alwaysApply: false
4+
---
5+
# C++ Programming Guidelines for libxlio
6+
7+
This guide is tailored for libxlio, a performance-critical networking library.
8+
9+
## Coding Style
10+
11+
**All code formatting and style rules are documented in `docs/coding-style.md`.**
12+
13+
Please refer to that document for:
14+
- Indentation rules
15+
- Line breaking conventions
16+
- Brace placement
17+
- Spacing rules
18+
- Naming conventions (prefixes: `m_`, `s_`, `g_`)
19+
- Pointer and reference declarations
20+
- Include statement ordering
21+
- Comment styles
22+
- Class layout
23+
- `auto` keyword usage
24+
25+
## Basic Principles
26+
27+
- Use English for all code and documentation.
28+
- Create necessary types and classes.
29+
- Use Doxygen style comments to document public classes and methods.
30+
- Follow the one-definition rule (ODR).
31+
- Prioritize performance without sacrificing code clarity.
32+
33+
## Functions
34+
35+
- Write focused functions with a single purpose and clear intent.
36+
- Keep functions readable and maintainable (avoid arbitrary instruction limits; focus on clarity).
37+
- Name functions with a verb and something else.
38+
- If it returns a boolean, use is_x or has_x, can_x, etc.
39+
- If it doesn't return anything (void), use execute_x or save_x, update_x, etc.
40+
- Avoid nesting blocks by:
41+
- Early checks and returns.
42+
- Extraction to utility functions.
43+
- Use standard library algorithms (std::for_each, std::transform, std::find, etc.) to avoid function nesting.
44+
- Reduce function parameters using structs or classes:
45+
- Use an object to pass multiple parameters.
46+
- Use an object to return multiple results.
47+
- Declare necessary types for input arguments and output.
48+
- Use a single level of abstraction.
49+
50+
## Data
51+
52+
- Don't abuse primitive types and encapsulate data in composite types.
53+
- Avoid data validations in functions and use classes with internal validation.
54+
- Prefer immutability for data.
55+
- Use const for data that doesn't change.
56+
- Use constexpr for compile-time constants.
57+
58+
## Classes
59+
60+
- Follow SOLID principles.
61+
- Prefer composition over inheritance.
62+
- Declare interfaces as abstract classes or concepts.
63+
- Write small classes with a single purpose.
64+
- Less than 200 instructions.
65+
- Less than 10 public methods.
66+
- Less than 10 properties.
67+
- Use the Rule of Five (or Rule of Zero) for resource management.
68+
- Make member variables private and provide getters/setters where necessary.
69+
- Use const-correctness for member functions.
70+
71+
## Exceptions
72+
73+
libxlio has a configurable exception handling mechanism. Follow these guidelines:
74+
75+
- Use exceptions sparingly in performance-critical code paths.
76+
- Prefer error codes for expected error conditions in hot paths.
77+
- Use exceptions for truly exceptional situations during initialization/setup.
78+
- Use custom exception classes (`xlio_exception`) when exceptions are needed.
79+
- If you catch an exception, it should be to:
80+
- Fix an expected problem.
81+
- Add context with additional information.
82+
- Otherwise, use a global handler.
83+
- **Rationale**: Exception handling overhead is inappropriate for data path operations in a performance-critical library.
84+
85+
## Memory Management
86+
87+
Memory management in libxlio prioritizes performance:
88+
89+
- Use custom memory pools and allocators for performance-critical allocations.
90+
- Raw pointers are acceptable and often preferred in hot paths.
91+
- Smart pointers (std::unique_ptr, std::shared_ptr) for non-performance-critical resource management.
92+
- Use RAII (Resource Acquisition Is Initialization) principles where they don't impact performance.
93+
- Avoid memory leaks by proper resource management.
94+
- Consider cache alignment and padding when designing data structures.
95+
- Use `xlio_allocator` and related custom allocators for frequently allocated objects.
96+
- Prefer stack allocation over heap allocation when possible.
97+
98+
## Performance-Critical Programming
99+
100+
libxlio is a performance-critical library. Apply these optimizations when appropriate:
101+
102+
- Use inline functions for hot paths where beneficial.
103+
- Consider cache line alignment (typically 64 bytes) for frequently accessed structures.
104+
- Use `likely`/`unlikely` compiler hints for branch prediction in hot paths.
105+
- Minimize allocations in the data path; prefer object pools and pre-allocation.
106+
- Prefer stack allocation over heap allocation when object lifetime allows.
107+
- Use `const` and `constexpr` aggressively to enable compiler optimizations.
108+
- Be mindful of false sharing in multi-threaded code.
109+
- Profile before optimizing; measure the impact of changes.
110+
- Document performance-critical sections and the reasoning behind optimizations.
111+
112+
## Testing
113+
114+
- Follow the Arrange-Act-Assert convention for tests.
115+
- Name test variables clearly.
116+
- Write unit tests for each public function.
117+
- Follow the Given-When-Then convention.
118+
- All features or bug fixes **must be tested** by unit tests.
119+
120+
## Project Structure
121+
122+
- Use modular architecture.
123+
- Organize code into logical directories.
124+
- Use automake and autotools.
125+
- Separate interface (.h) from implementation (.cpp).
126+
- Use namespaces to organize code logically.
127+
128+
## Standard Library
129+
130+
- Use the C++ Standard Library when it doesn't compromise performance.
131+
- Use std::vector, std::map, std::unordered_map, etc. for collections (except in hot paths).
132+
- Use std::chrono for time-related operations.
133+
- Consider custom implementations for performance-critical data structures.
134+
135+
## Concurrency
136+
137+
libxlio is a multi-threaded library. Thread safety is critical:
138+
139+
- Use std::thread, std::mutex, std::lock_guard for thread safety.
140+
- Use std::atomic for atomic operations.
141+
- Avoid data races by proper synchronization.
142+
- Use thread-safe data structures when necessary.
143+
- Be mindful of lock contention in hot paths.
144+
- Consider lock-free algorithms for performance-critical sections.
145+
- Document thread-safety guarantees for all public APIs.

‎.cursor/rules/commit-msg.mdc‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
---
2+
description: Write a commit message
3+
alwaysApply: false
4+
---
5+
6+
Generate a well-formatted commit message for the currently staged changes following the project's conventions.
7+
8+
## Prerequisites
9+
Before writing the commit message:
10+
1. Review the staged changes using `git diff --staged` to understand what was modified
11+
2. Identify the Redmine issue ID (check branch name, recent commits, or ask user if not found)
12+
3. Retrieve git configuration:
13+
- User name: `git config user.name`
14+
- User email: `git config user.email`
15+
16+
## Template Format
17+
```
18+
issue: <redmine_issue_id> <concise-title>
19+
20+
<detailed-body>
21+
22+
Signed-off-by: <user_full_name> <user_email>
23+
```
24+
25+
## Writing Guidelines
26+
27+
### Subject Line (First Line)
28+
- **Format**: `issue: <redmine_issue_id> <concise-title>`
29+
- **Maximum length**: 51 characters (for optimal git log display)
30+
- **Style**: Use imperative mood (e.g., "Add feature" not "Added feature")
31+
- **Content**: Brief, actionable description of the change
32+
- **Example**: `issue: 12345 Fix memory leak in buffer pool`
33+
34+
### Body
35+
- **Line length**: Maximum 72 characters per line (for readability in various git tools)
36+
- **Content**:
37+
- Explain WHAT changed and WHY (not HOW - the code shows that)
38+
- Reference any technical decisions or trade-offs
39+
- Mention side effects or related changes
40+
- Use bullet points for multiple changes
41+
- **Tone**: Clear, technical, and informative
42+
- Leave a blank line between subject and body
43+
44+
### Sign-off
45+
- **Format**: `Signed-off-by: Full Name <[email protected]>`
46+
- Use values from git config (never hardcode)
47+
48+
## Error Handling
49+
- If Redmine issue ID is missing: Check branch name first (e.g., "bugfix/12345-description"), then ask user
50+
- If staged changes are empty: Alert user and abort
51+
- If git config is incomplete: Ask user to configure git first
52+
53+
## Examples
54+
55+
### Example 1: Feature Addition
56+
```
57+
issue: 12345 Add zero-copy receive path
58+
59+
Implement zero-copy receive mechanism using memory mapping
60+
to reduce CPU overhead in high-throughput scenarios.
61+
62+
- Add new RX buffer pool with mmap allocation
63+
- Integrate with existing ring buffer architecture
64+
- Add configuration option XLIO_RX_ZERO_COPY
65+
66+
Performance tests show 15% reduction in CPU usage for
67+
large packet workloads.
68+
69+
Signed-off-by: John Doe <[email protected]>
70+
```
71+
72+
### Example 2: Bug Fix
73+
```
74+
issue: 45678 Fix race condition in CQ polling
75+
76+
Resolve race between CQ event handler and polling thread
77+
that caused occasional missed completions.
78+
79+
Added mutex protection around CQ state transitions and
80+
ensured proper ordering of event acknowledgment.
81+
82+
Signed-off-by: Jane Smith <[email protected]>
83+
```
84+
85+
## Process
86+
1. Run `git diff --staged` to analyze changes
87+
2. Extract/confirm Redmine issue ID
88+
3. Generate subject line (check 51 char limit)
89+
4. Write body explaining the changes clearly
90+
5. Add sign-off with git config values
91+
6. Verify format compliance before presenting to user

‎.cursor/rules/evaluate-bug.mdc‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
description: Evaluate and analyze bugs
3+
alwaysApply: false
4+
---
5+
6+
Investigate and analyze a Redmine ticket to understand the root cause of a bug.
7+
8+
## Prerequisites
9+
**Stop and ask user to install Redmine MCP if unavailable.**
10+
11+
If ticket number is not provided, request it from the user.
12+
13+
## Phase 1: Investigation
14+
15+
### Ticket Analysis
16+
1. Fetch the full ticket using `yai__get_tickets` with ticket ID
17+
2. Extract key information:
18+
- Bug description and reproduction steps
19+
- Affected versions, components, priority
20+
- Attachments (logs, screenshots, stack traces)
21+
3. Review comments using `yai__get_comments`
22+
4. Search for similar issues using `yai__get_similar_issues`
23+
24+
### Codebase Investigation
25+
1. Locate affected code components (use semantic search and grep)
26+
2. Trace execution path from entry point to bug location
27+
3. Review recent changes to affected files (git history)
28+
4. Examine error handling and edge cases
29+
5. Check existing tests related to the functionality
30+
31+
### Data Gathering
32+
- Collect error messages, stack traces, logs
33+
- Document current vs. expected behavior
34+
- Note environmental factors (OS, versions, config)
35+
36+
## Phase 2: Root Cause Analysis
37+
38+
Provide a clear explanation of:
39+
- **What the user experiences**: Observable symptoms
40+
- **Technical root cause**: The actual defect in code/logic
41+
- **Why it exists**: Contributing factors (race condition, missing validation, incorrect assumption, etc.)
42+
- **Impact scope**: Which features/users are affected
43+
44+
## Phase 3: Visual Illustration
45+
46+
Create diagrams to illustrate:
47+
1. **Bug flow diagram**: Sequence/flow showing how the bug manifests
48+
2. **Architecture context**: Components involved and their relationships
49+
50+
Use mermaid or ASCII diagrams for clarity.
51+
52+
## Notes
53+
- If insufficient information exists, clearly state what's missing and ask user
54+
- Validate all assumptions by examining actual code
55+
56+
## Next Steps
57+
58+
After completing this evaluation:
59+
- **If fix is needed**: Use `@solve-bug.mdc [ticket#]` to generate solution proposals
60+
- **If more investigation needed**: Document questions and continue research
61+
- **If ticket is invalid**: Update ticket status with findings

0 commit comments

Comments
 (0)