Added docs folder
This commit is contained in:
101
docs/develoepr-guide/ai-reviewer-output-format.md
Normal file
101
docs/develoepr-guide/ai-reviewer-output-format.md
Normal file
@@ -0,0 +1,101 @@
|
||||
# AI Code Reviewer — Output Comment Format
|
||||
|
||||
## 1. Summary Comment
|
||||
|
||||
The summary comment is posted by the bot as a **top-level PR comment** after the review is complete.
|
||||
It provides a high-level assessment of the entire diff.
|
||||
|
||||
### Format
|
||||
|
||||
```
|
||||
🔴 Code quality assessment: <Poor | Acceptable | Excellent>
|
||||
|
||||
ℹ️ Conclusion: <Short explanation of the most critical finding and its impact>
|
||||
|
||||
❌ Merge: No - <reason>
|
||||
✅ Merge: Yes
|
||||
```
|
||||
|
||||
### Example
|
||||
|
||||
> 🔴 Code quality assessment: Poor
|
||||
>
|
||||
> ℹ️ Conclusion: The commit introduces a critical bug where `Stopwatch.StartNew()` is called twice on consecutive lines (lines 15–16 in `samples/AR/App.cs`). The duplicate assignment statement must be removed.
|
||||
>
|
||||
> ❌ Merge: No - blocking issue must be resolved first
|
||||
|
||||
### Quality Levels
|
||||
|
||||
| Badge | Label | Meaning |
|
||||
|---|---|---|
|
||||
| 🔴 | Poor | Blocking issues found, must not merge |
|
||||
| 🟡 | Acceptable | Minor suggestions only |
|
||||
| ✅ | Excellent | No issues found |
|
||||
|
||||
---
|
||||
|
||||
## 2. Inline Comments
|
||||
|
||||
Inline comments are posted **directly on the changed lines** in the diff.
|
||||
They follow the [**Conventional Comments**](https://conventionalcomments.org/) approach to make severity and intent immediately clear.
|
||||
|
||||
### Conventional Comments Format
|
||||
|
||||
```
|
||||
<emoji> <label> (<optional decoration>): <subject>
|
||||
|
||||
<body — explanation of the issue>
|
||||
|
||||
💻 Suggested Code:
|
||||
<code block with the fix>
|
||||
```
|
||||
|
||||
### Example
|
||||
|
||||
Posted inline on line 16 of `samples/AR/App.cs`:
|
||||
|
||||
---
|
||||
|
||||
> 🔴 Issue (Blocking): Duplicate Stopwatch initialization
|
||||
>
|
||||
> The `Stopwatch.StartNew()` call on line 15 is repeated on line 16, which overwrites the first instance. This appears to be an accidental duplicate that should be removed.
|
||||
>
|
||||
> 💻 Suggested Code:
|
||||
> ```csharp
|
||||
> public void Run(string reportName, Dictionary<string, object[]>? reportParameters)
|
||||
> {
|
||||
> var sw = Stopwatch.StartNew();
|
||||
> Trace.WriteLine($"{sw.ElapsedMilliseconds} : Start { reportName}!");
|
||||
> _reportExport.Run(reportName, reportParameters, sw);
|
||||
> sw.Stop();
|
||||
> Trace.WriteLine($"{sw.ElapsedMilliseconds} : End!");
|
||||
> }
|
||||
> ```
|
||||
|
||||
|
||||
## 3. Request Changes or Approve Pull Request
|
||||
|
||||
After posting comments, the bot submits a **formal PR review** with one of two states.
|
||||
|
||||
### Request Changes
|
||||
|
||||
Triggered when one or more **Blocking** issues are found.
|
||||
|
||||
```
|
||||
Status: ❌ Request Changes
|
||||
```
|
||||
|
||||
The PR is blocked from merging (if branch protection rules are enabled) until:
|
||||
- The author fixes the blocking issues
|
||||
- The bot re-reviews after a new commit (`synchronize` event)
|
||||
- A human reviewer overrides the block
|
||||
|
||||
---
|
||||
|
||||
### Approved
|
||||
|
||||
Triggered when no blocking issues are found.
|
||||
|
||||
```
|
||||
Status: ✅ Approved
|
||||
```
|
||||
41
docs/develoepr-guide/extension-of-rules.md
Normal file
41
docs/develoepr-guide/extension-of-rules.md
Normal file
@@ -0,0 +1,41 @@
|
||||
# Review Prompt Extension
|
||||
|
||||
The Kodo tool supports the ability to extend the built-in prompt for review. This can be done in the following way
|
||||
|
||||
## 1. The CONSTITUTION.md file
|
||||
|
||||
You can create a `.review` folder if it does not exist and add a `CONSTITUTION.md` file to this folder, which will contain part of the prompt that will be read by the tool during execution.
|
||||
|
||||
```
|
||||
my-project/
|
||||
├── .review/ ← Create this folder
|
||||
│ └── CONSTITUTION.md ← Your custom rules
|
||||
├── src/
|
||||
└── ...
|
||||
```
|
||||
|
||||
The `.review` folder must be placed in the **root of your repository**.
|
||||
|
||||
### 1.1. Example of the CONSTITUTION.md file.
|
||||
|
||||
Example of a file you can create
|
||||
|
||||
``` markdown
|
||||
# Additional rules for code reviews.
|
||||
1. Do not check dependency declarations in code files
|
||||
2. Do not check namespaces
|
||||
|
||||
# Knowledge about the project structure
|
||||
This project contains the following modules:
|
||||
1. DataEngine - the core for processing user data.
|
||||
2. Viewer - a tool for visualizing user data.
|
||||
```
|
||||
|
||||
### 1.2. Recommendations for the CONSTITUTION.md file
|
||||
|
||||
There are some recommendations for creating content for this file:
|
||||
|
||||
1. Do not provide contradictory instructions and information.
|
||||
2. Provide a detailed description of any modules and rules.
|
||||
3. Do not make this file large, as it will be part of the prompt, which has a limited context.
|
||||
|
||||
46
docs/develoepr-guide/faq-troubleshooting.md
Normal file
46
docs/develoepr-guide/faq-troubleshooting.md
Normal file
@@ -0,0 +1,46 @@
|
||||
# AI Code Reviewer — Troubleshooting: Reviewer Did Not Run
|
||||
|
||||
## Quick Checklist
|
||||
|
||||
Before diving deeper, verify the basics:
|
||||
|
||||
- The workflow file exists at `.gitea/workflows/kodo-reviewer.yaml`
|
||||
- Secrets `CC_GITEATOKEN` and `CC_API_KEY` are set in repository settings
|
||||
- The runner `kodo-review` is online and available
|
||||
- The PR title does **not** contain `[no ai]`
|
||||
- The event that triggered the workflow matches one of the configured triggers
|
||||
|
||||
---
|
||||
|
||||
## Common Causes & Fixes
|
||||
|
||||
### 1. Secrets are missing or misconfigured
|
||||
|
||||
If `CC_GITEATOKEN` or `CC_API_KEY` are not set, the action will fail silently or error out.
|
||||
|
||||
**How to check:**
|
||||
1. Go to repository **Settings → Secrets**
|
||||
2. Verify both secrets exist:
|
||||
- `CC_GITEATOKEN` — Gitea token with read/write access to PRs
|
||||
- `CC_API_KEY` — Anthropic API key
|
||||
|
||||
**Fix:** Add/regenerate missing secrets or contact with `devops` team.
|
||||
|
||||
---
|
||||
|
||||
### 2. PR title contains `[no ai]`
|
||||
|
||||
The action checks for `[no ai]` in the PR title and skips execution if found.
|
||||
|
||||
**Fix:** Remove `[no ai]` from the PR title and push a new commit or re-open the PR.
|
||||
|
||||
---
|
||||
|
||||
## Still Not Working?
|
||||
|
||||
Provide the following information when asking for help from `devops` team:
|
||||
|
||||
- Runner name and status (`kodo-review`)
|
||||
- Workflow run URL
|
||||
- Event that was expected to trigger the review
|
||||
- Observed and expected behavior
|
||||
45
docs/develoepr-guide/how-to-integrate.md
Normal file
45
docs/develoepr-guide/how-to-integrate.md
Normal file
@@ -0,0 +1,45 @@
|
||||
# CI/CD integration for Gitea VCS
|
||||
|
||||
## Introduction
|
||||
|
||||
Manually launching and configuring the tool is quite a challenging task and requires a deep understanding of the AI service being used and the built-in operating rules. Therefore, to simplify the task, we have created pre-prepared actions for launching and updating the tool.
|
||||
|
||||
## 1. User for review
|
||||
|
||||
For the tool to work, you need to add a user who will perform the review. Add to `CODEOWNERS` file for repository if you want it to be assigned automatically, or add it manually if necessary.
|
||||
|
||||
Use this Gitea user by default: `@kodobot`.
|
||||
|
||||
## 2. Prepared step script for Gitea
|
||||
|
||||
Use the following script to integrate the tool into your Gitea actions. All necessary improvements and integrations must be performed independently by each team. Add your `.gitea/workflows/kodo-reviewer.yaml` file with the following content
|
||||
|
||||
``` yml
|
||||
name: AI Code Reviewer Assistant for Gitea
|
||||
on:
|
||||
issue_comment:
|
||||
types: [created]
|
||||
pull_request_review_comment:
|
||||
types: [created]
|
||||
pull_request:
|
||||
types: [opened, synchronize, reopened]
|
||||
jobs:
|
||||
claude-assistant:
|
||||
runs-on: kodo-review
|
||||
steps:
|
||||
- name: Run AI Code Reviewer
|
||||
uses: https://code.wynenterprise.io/kodo/reviewer@main
|
||||
with:
|
||||
gitea_token: ${{ secrets.CC_GITEATOKEN }}
|
||||
anthropic_api_key: ${{ secrets.CC_API_KEY }}
|
||||
```
|
||||
|
||||
This script will run automatically when a Pull Request is created or updated. If necessary, you can start it manually via the Gitea interface and add additional conditions required for start.
|
||||
|
||||
## 2.1. Environment variables for script
|
||||
|
||||
When configuring the tool, always strictly adhere to the following rules for certain environment variables:
|
||||
|
||||
1. The `secrets.CC_GITEATOKEN` environment variable must contain a token for the user @kodobot. **Request this token from the devops team.**
|
||||
2. The `secrets.CC_API_KEY` environment variable must contain a token for access ti AI model. **Request this token from the devops team.**
|
||||
|
||||
Reference in New Issue
Block a user