Skip to content

Commit e4e3fb7

Browse files
alexcoderabbitaialexcoderabbitai
authored
add linked issues guide (#271)
* add linked issues guide * move down * reorder * add specific information
1 parent d64d6d9 commit e4e3fb7

10 files changed

+189
-7
lines changed

‎docs/guides/agent_chat.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: Chat and Agentic Chat
33
sidebar_label: Chat and Agentic Chat
44
description: Learn about CodeRabbit Pro's chat and agentic chat system
5-
sidebar_position: 8
5+
sidebar_position: 3
66
---
77

88
# CodeRabbit Chat

‎docs/guides/commands.md

+7
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,10 @@
1+
---
2+
title: Commands
3+
sidebar_label: Commands
4+
description: Learn how to control CodeRabbit using commands in pull request comments
5+
sidebar_position: 1
6+
---
7+
18
# CodeRabbit Commands
29

310
> Control your code reviews directly from pull request comments using CodeRabbit's command system. Each command starts with `@coderabbitai` followed by the specific action you want to take.

‎docs/guides/custom-reports.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: Custom Reports
33
sidebar_label: Custom Reports
44
description: Learn how to create custom reports with CodeRabbit Pro's flexible reporting system
5-
sidebar_position: 7
5+
sidebar_position: 8
66
---
77

88
```mdx-code-block

‎docs/guides/issue-chat.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: Issue Chat
33
sidebar_label: Issue Chat
44
description: Learn how to use CodeRabbit's chat capabilities within issues
5-
sidebar_position: 10
5+
sidebar_position: 4
66
---
77

88
```mdx-code-block

‎docs/guides/issue-creation.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: Issue Creation
33
sidebar_label: Issue Creation
44
description: Learn how to create issues directly through CodeRabbit
5-
sidebar_position: 9
5+
sidebar_position: 5
66
---
77

88
```mdx-code-block

‎docs/guides/linked-issues.md

+175
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
---
2+
title: Linked Issues
3+
sidebar_label: Linked Issues
4+
description: Learn how to effectively use linked issues with CodeRabbit for better pull request assessments
5+
sidebar_position: 6
6+
---
7+
8+
# Linked Issues
9+
10+
CodeRabbit provides intelligent assessment of linked issues to validate whether pull requests properly address their requirements. This guide explains how to effectively use linked issues and write clear issue descriptions for optimal results.
11+
12+
## Understanding Linked Issues
13+
14+
A linked issue is one that is explicitly referenced in your pull request description using platform-specific syntax:
15+
16+
- GitHub: `fixes #123`, `closes #123`, `resolves #123`
17+
- GitLab: `closes #123`, `fixes #123`, or full URLs
18+
- Jira/Linear: Full URLs to tickets
19+
20+
When CodeRabbit detects linked issues, it analyzes them against your pull request changes to determine if the requirements are met:
21+
22+
![Linked Issue Assessment Example](/img/guides/linked-issue.png)
23+
24+
## Best Practices for Issue Writing
25+
26+
### Issue Titles
27+
28+
Create descriptive, technical titles that clearly state the goal:
29+
30+
✅ Good Examples:
31+
32+
- "Add PrismaLint integration to configuration flow"
33+
- "Fix race condition in user authentication"
34+
- "Implement caching for GraphQL queries"
35+
36+
❌ Poor Examples:
37+
38+
- "Fix bug"
39+
- "Update code"
40+
- "Improve performance"
41+
42+
### Issue Descriptions
43+
44+
Write comprehensive descriptions that provide clear technical context:
45+
46+
1. **Problem Statement**
47+
48+
- Clearly describe what needs to be changed
49+
- Include technical details about affected components
50+
- Reference specific files or functions if known
51+
52+
2. **Expected Solution**
53+
- Outline the desired implementation approach
54+
- Include code examples or pseudo-code when relevant
55+
- List specific acceptance criteria
56+
57+
Example Description:
58+
59+
```markdown
60+
Problem:
61+
The configuration system doesn't validate Prisma schema files before deployment,
62+
leading to potential runtime errors.
63+
64+
Solution:
65+
Integrate PrismaLint into the configuration flow to:
66+
67+
- Validate schema files during PR checks
68+
- Enforce consistent naming conventions
69+
- Prevent common Prisma anti-patterns
70+
71+
Affected Components:
72+
73+
- Configuration validation pipeline
74+
- CI/CD workflow
75+
- Schema validation logic
76+
77+
Acceptance Criteria:
78+
79+
- [ ] PrismaLint runs on all PR checks
80+
- [ ] Failed validations block merging
81+
- [ ] Clear error messages for schema issues
82+
```
83+
84+
### Consistent Terminology
85+
86+
Use consistent terminology between issues and pull requests:
87+
88+
✅ Good:
89+
90+
- Use the same technical terms consistently
91+
- Reference components with their exact names
92+
- Maintain consistent naming patterns
93+
94+
❌ Poor:
95+
96+
- Mixing different terms for the same component
97+
- Using vague or non-technical language
98+
- Inconsistent capitalization or formatting
99+
100+
## Linking Issues Effectively
101+
102+
### In Pull Requests
103+
104+
1. **Direct References**
105+
106+
```markdown
107+
Fixes #123
108+
Resolves organization/repo#456
109+
Closes https://github.com/org/repo/issues/789
110+
```
111+
112+
2. **Multiple Issues**
113+
114+
```markdown
115+
This PR addresses:
116+
117+
- Fixes #123
118+
- Closes #456
119+
- Resolves https://jira.company.com/browse/PROJ-789
120+
```
121+
122+
### Cross-References
123+
124+
For better traceability:
125+
126+
1. Add PR references in issue comments
127+
2. Use complete URLs when linking external systems
128+
3. Maintain bidirectional links between related issues
129+
130+
## How CodeRabbit Assesses Linked Issues
131+
132+
CodeRabbit evaluates linked issues by:
133+
134+
1. Analyzing issue titles and descriptions
135+
2. Comparing changes in the pull request
136+
3. Validating if requirements are met
137+
4. Providing an assessment with:
138+
- ✅: If the objective has been addressed in the PR. The 'Explanation' column will be left blank.
139+
- ❌: If the objective has not been addressed in the PR. Here a brief explanation is added to the 'Explanation' column.
140+
- ❓: If it is unclear whether the objective has been addressed. Here a brief explanation is added to the 'Explanation' column.
141+
142+
:::note
143+
Only the issue title and description are considered in the assessment. Comments and discussion threads are not currently analyzed.
144+
:::
145+
146+
## Tips for Better Assessments
147+
148+
1. **Be Specific**
149+
150+
- Include clear, measurable objectives
151+
- List specific technical requirements
152+
- Reference affected code components
153+
154+
2. **Provide Context**
155+
156+
- Explain why changes are needed
157+
- Document current behavior
158+
- Describe expected outcomes
159+
160+
3. **Use Technical Details**
161+
162+
- Include file paths when known
163+
- Reference specific functions or classes
164+
- Mention relevant technologies
165+
166+
4. **Keep It Focused**
167+
- One main objective per issue
168+
- Clear scope boundaries
169+
- Specific acceptance criteria
170+
171+
## Related Resources
172+
173+
- [Review Instructions](./review-instructions.md)
174+
- [Issue Chat](./issue-chat.md)
175+
- [Issue Creation](./issue-creation.md)

‎docs/guides/ondemand-reports.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: On-demand Reports
33
sidebar_label: On-demand Reports
44
description: CodeRabbit offers a way to generate on-demand reports using a simple API request
5-
sidebar_position: 8
5+
sidebar_position: 9
66
---
77

88
```mdx-code-block

‎docs/guides/review-instructions.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ description:
55
CodeRabbit offers various customization options to tailor the reviews to your
66
specific requirements. Customizations can be made using one of the below
77
options.
8-
sidebar_position: 3
8+
sidebar_position: 2
99
---
1010

1111
The guide explains how to add custom review instructions for the entire project.

‎docs/guides/scheduled-reports.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: Scheduled Reports
33
sidebar_label: Scheduled Reports
44
description: Learn how to set up automated recurring reports with CodeRabbit Pro
5-
sidebar_position: 6
5+
sidebar_position: 7
66
---
77

88
```mdx-code-block

‎static/img/guides/linked-issue.png

14.8 KB
Loading

0 commit comments

Comments
 (0)