diff --git a/ai-reviewer-output-format.md b/ai-reviewer-output-format.md index d39cc43..8158267 100644 --- a/ai-reviewer-output-format.md +++ b/ai-reviewer-output-format.md @@ -1,6 +1,6 @@ -# AI Code Reviewer — Output Comment Format +# 📋 AI Code Reviewer — Output Comment Format -## 1. Summary Comment +## 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. @@ -34,7 +34,7 @@ It provides a high-level assessment of the entire diff. --- -## 2. Inline Comments +## 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. @@ -73,11 +73,11 @@ Posted inline on line 16 of `samples/AR/App.cs`: > ``` -## 3. Request Changes or Approve Pull Request +## 3. 🔖 Request Changes or Approve Pull Request After posting comments, the bot submits a **formal PR review** with one of two states. -### Request Changes +### ❌ Request Changes Triggered when one or more **Blocking** issues are found. @@ -92,7 +92,7 @@ The PR is blocked from merging (if branch protection rules are enabled) until: --- -### Approved +### ✅ Approved Triggered when no blocking issues are found. diff --git a/extension-of-rules.md b/extension-of-rules.md index e474183..cdff54c 100644 --- a/extension-of-rules.md +++ b/extension-of-rules.md @@ -1,8 +1,8 @@ -# Review Prompt Extension +# 📐 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 +## 📁 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. @@ -16,7 +16,7 @@ my-project/ The `.review` folder must be placed in the **root of your repository**. -### 1.1. Example of the CONSTITUTION.md file. +### ✏️ 1.1. Example of the CONSTITUTION.md file. Example of a file you can create @@ -31,11 +31,10 @@ This project contains the following modules: 2. Viewer - a tool for visualizing user data. ``` -### 1.2. Recommendations for the CONSTITUTION.md file +### 💡 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. - diff --git a/faq-troubleshooting.md b/faq-troubleshooting.md index c84db4c..e2f2e05 100644 --- a/faq-troubleshooting.md +++ b/faq-troubleshooting.md @@ -1,17 +1,17 @@ -# AI Code Reviewer — Troubleshooting: Reviewer Did Not Run +# 🔧 Troubleshooting: Reviewer Did Not Run -## Quick Checklist +## ✅ Quick Checklist Before diving deeper, verify the basics: -- The workflow file exists at `.gitea/workflows/kodo-reviewer.yaml` -- The secrets `CC_GITEATOKEN` and `CC_API_KEY` are set in the repository settings by the `devops` team -- The runner `kodo-review` is online and available -- The PR title does **not** contain `[no ai]` +- 📄 The workflow file exists at `.gitea/workflows/kodo-reviewer.yaml` +- 🔑 The secrets `CC_GITEATOKEN` and `CC_API_KEY` are set in the repository settings by the `devops` team +- 🖥️ The runner `kodo-review` is online and available +- 🏷️ The PR title does **not** contain `[no ai]` --- -## Common Causes & Fixes +## 🔍 Common Causes & Fixes ### 1. PR title contains `[no ai]` @@ -21,7 +21,7 @@ The action checks for `[no ai]` in the PR title and skips execution if found. --- -## Still Not Working? +## 📨 Still Not Working? Provide the following information when asking for help from `devops` team: diff --git a/how-to-integrate.md b/how-to-integrate.md index 8466f2f..e892eff 100644 --- a/how-to-integrate.md +++ b/how-to-integrate.md @@ -1,15 +1,15 @@ -# CI/CD integration for Gitea VCS +# 🔌 CI/CD integration for Gitea VCS -## Introduction +## 📖 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 +## 👤 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 +## 📄 2. Prepared step script for Gitea Use the following script to integrate the Kodo tool into your Gitea actions. Add your `.gitea/workflows/kodo-reviewer.yaml` file with the following content @@ -35,7 +35,7 @@ jobs: 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 +## 🔑 2.1. Environment variables for script When configuring the tool, always strictly adhere to the following rules for certain environment variables: @@ -43,4 +43,3 @@ When configuring the tool, always strictly adhere to the following rules for cer 2. The `secrets.CC_API_KEY` environment variable must contain a token for access to AI model. **Important:** All these environment variables must be created in advance by the `devops` team, and you use them as they are. - diff --git a/how-to-use.md b/how-to-use.md index 5c607bc..c03565f 100644 --- a/how-to-use.md +++ b/how-to-use.md @@ -1,8 +1,8 @@ -# Code Review with Kodo +# 👩‍💻 Code Review with Kodo Kodo is an AI reviewer that automatically checks your code in Pull Requests and answers questions about the code. -## Getting Started +## 🚀 Getting Started To get an AI review on your Pull Request: @@ -12,14 +12,14 @@ To get an AI review on your Pull Request: That's it — Kodo will automatically review your code once added. -## Starting a Review Manually +## 🔁 Starting a Review Manually If you need to re-run the review or trigger it at a specific moment, just mention `@kodobot` in any PR comment: ``` @kodobot please review ``` -## Skipping the Review +## ⏭️ Skipping the Review **Don't want Kodo to review a specific PR?** Simply don't add `@kodobot` as a reviewer. @@ -31,7 +31,7 @@ Add `[no ai]` to the Pull Request title: Kodo will not trigger on this PR — neither on creation nor on new pushes. -## Asking Kodo a Question +## 💬 Asking Kodo a Question You can ask Kodo anything about the code directly in a PR comment: ``` @@ -39,4 +39,4 @@ You can ask Kodo anything about the code directly in a PR comment: @kodobot is there a risk of a race condition here? ``` -Kodo will reply in the comments. \ No newline at end of file +Kodo will reply in the comments. diff --git a/limitations-and-best-practices.md b/limitations-and-best-practices.md index d80510c..d58f04c 100644 --- a/limitations-and-best-practices.md +++ b/limitations-and-best-practices.md @@ -1,30 +1,30 @@ -# Limitations & Best Practices +# ⚠️ Limitations & Best Practices -## Limitations +## 🚧 Limitations -### Context & Understanding +### 🧠 Context & Understanding - **No business logic awareness** — AI only sees code, not product requirements - **Limited context window** — the model has its own context window, which can hold a limited amount of information. - **No decision history** — does not store the history of previous executions, only reads existing information in Pull Request. - **Hallucinations** — may confidently suggest incorrect solutions or non-existent APIs - **Large PR degradation** — review quality drops significantly for PRs with 1000+ lines changed -### Process Constraints +### 🔄 Process Constraints - **Does not replace humans** — final decision always belongs to the author and human reviewer - **Slower on large PRs** — response time grows with the size of changes - **No memory between PRs** — each review starts from scratch with no prior context - **Trigger dependency** — only runs on configured events (`[no ai]` in title disables it) -## Best Practices +## ✅ Best Practices -### Writing PRs for Better AI Review +### 📝 Writing PRs for Better AI Review - **Keep PRs small and focused** — one logical change per PR, ideally under 400 lines - **Write a clear PR description** — explain *what* and *why*, not just *what changed* - **Add `[no ai]` to title** when the PR is trivial (version bumps, typo fixes, formatting) - **Split refactoring from feature changes** — mixed PRs confuse both AI and humans -### Working with AI Comments +### 🤝 Working with AI Comments - **Treat AI comments as suggestions, not mandates** — use your judgment - **Verify all suggested code** before applying — AI can introduce bugs @@ -32,7 +32,7 @@ - **Don't blindly resolve AI comments** — acknowledge or explain why you disagree - **Re-trigger review after major changes** by pushing a new commit -### Security +### 🔒 Security - **Never put secrets in PR descriptions or comments** — AI logs may capture them - **Store `anthropic_api_key` and `gitea_token` in repository secrets**, not in workflow files diff --git a/reviewer-token.md b/reviewer-token.md index 0379294..c46b335 100644 --- a/reviewer-token.md +++ b/reviewer-token.md @@ -1,6 +1,6 @@ -# Gitea Token Setup for AI Code Reviewer +# ⚙️ Gitea Token Setup for AI Code Reviewer -## Required Token Permissions +## 🔑 Required Token Permissions | Permission | Level | Reason | |---|---|---| @@ -10,7 +10,7 @@ All other permissions (`activitypub`, `misc`, `notification`, `organization`, `package`) should be set to **No Access**. -## How to Generate the Token +## 🛠️ How to Generate the Token 1. Log in to Gitea as the **bot account** that will be assigned as a reviewer 2. Go to **Settings** → **Applications** (top right avatar → Settings → Applications) @@ -22,7 +22,7 @@ All other permissions (`activitypub`, `misc`, `notification`, `organization`, `p 6. Click **Generate Token** 7. **Copy the token immediately** — it will not be shown again -## Adding the Token to Your Repository +## 📦 Adding the Token to Your Repository 1. Go to your repository → **Settings** → **Secrets** 2. Click **Add Secret** @@ -31,7 +31,7 @@ All other permissions (`activitypub`, `misc`, `notification`, `organization`, `p - **Value**: paste the token generated above 4. Click **Save** -## Important Notes +## ⚠️ Important Notes - The token must belong to the account that is **assigned as a reviewer** on pull requests — this is how the reviewer verification check works -- Treat the token as a password — never commit it to the repository \ No newline at end of file +- Treat the token as a password — never commit it to the repository