cozystack-cozystack/docs/agents/contributing.md

Instructions for AI Agents

Guidelines for AI agents contributing to Cozystack.

Checklist for Creating a Pull Request

• Changes are made and tested
• Commit message uses correct [component] prefix
• Commit is signed off with --signoff
• Branch is rebased on upstream/main (no extra commits)
• PR body includes description and release note
• PR is pushed and created with gh pr create

How to Commit and Create Pull Requests

1. Make Your Changes

Edit the necessary files in the codebase.

2. Commit with Proper Format

Use the [component] prefix and --signoff flag:

git commit --signoff -m "[component] Brief description of changes"

Component prefixes:

• System: [dashboard], [platform], [cilium], [kube-ovn], [linstor], [fluxcd], [cluster-api]
• Apps: [postgres], [mariadb], [redis], [kafka], [clickhouse], [virtual-machine], [kubernetes]
• Other: [tests], [ci], [docs], [maintenance]

Examples:

git commit --signoff -m "[dashboard] Add config hash annotations to restart pods on config changes"
git commit --signoff -m "[postgres] Update operator to version 1.2.3"
git commit --signoff -m "[docs] Add installation guide"

3. Rebase on upstream/main (if needed)

If your branch has extra commits, clean it up:

# Fetch latest
git fetch upstream

# Create clean branch from upstream/main
git checkout -b my-feature upstream/main

# Cherry-pick only your commit
git cherry-pick <your-commit-hash>

# Force push to your branch
git push -f origin my-feature:my-branch-name

4. Push Your Branch

git push origin <branch-name>

5. Create Pull Request

Write the PR body to a temporary file:

cat > /tmp/pr_body.md << 'EOF'
## What this PR does

Brief description of the changes.

Changes:
- Change 1
- Change 2

### Release note

```release-note
[component] Description for changelog

EOF

Create the PR:

```bash
gh pr create --title "[component] Brief description" --body-file /tmp/pr_body.md

Clean up:

rm /tmp/pr_body.md

Addressing AI Bot Reviewer Comments

When the user asks to fix comments from AI bot reviewers (like Qodo, Copilot, etc.):

1. Get PR Comments

View all comments on the pull request:

gh pr view <PR-number> --comments

Or for the current branch:

gh pr view --comments

2. Review Each Comment Carefully

Important: Do NOT blindly apply all suggestions. Each comment should be evaluated:

• Consider context - Does the suggestion make sense for this specific case?
• Check project conventions - Does it align with Cozystack patterns?
• Evaluate impact - Will this improve code quality or introduce issues?
• Question validity - AI bots can be wrong or miss context

When to apply:

• ✅ Legitimate bugs or security issues
• ✅ Clear improvements to code quality
• ✅ Better error handling or edge cases
• ✅ Conformance to project conventions

When to skip:

• ❌ Stylistic preferences that don't match project style
• ❌ Over-engineering simple code
• ❌ Changes that break existing patterns
• ❌ Suggestions that show misunderstanding of the code

3. Apply Valid Fixes

Make changes addressing the valid comments. Use your judgment.

4. Leave Changes Uncommitted

Critical: Do NOT commit or push the changes automatically.

Leave the changes in the working directory so the user can:

• Review the fixes
• Decide whether to commit them
• Make additional adjustments if needed

# After making changes, show status but DON'T commit
git status
git diff

The user will commit and push when ready.

Code Review Comments

When asked to fix code review comments, always work only with unresolved (open) comments. Resolved comments should be ignored as they have already been addressed.

Getting Unresolved Review Comments

Use GitHub GraphQL API to fetch only unresolved review comments from a pull request:

gh api graphql -F owner=cozystack -F repo=cozystack -F pr=<PR_NUMBER> -f query='
query($owner: String!, $repo: String!, $pr: Int!) {
  repository(owner: $owner, name: $repo) {
    pullRequest(number: $pr) {
      reviewThreads(first: 100) {
        nodes {
          isResolved
          comments(first: 100) {
            nodes {
              id
              path
              line
              author { login }
              bodyText
              url
              createdAt
            }
          }
        }
      }
    }
  }
}' --jq '.data.repository.pullRequest.reviewThreads.nodes[] | select(.isResolved == false) | .comments.nodes[]'

Filtering for Unresolved Comments

The key filter is select(.isResolved == false) which ensures only unresolved review threads are processed. Each thread can contain multiple comments, but if the thread is resolved, all its comments should be ignored.

Working with Review Comments

1. Fetch unresolved comments using the GraphQL query above
2. Parse the results to identify:
   • File path (path)
   • Line number (line or originalLine)
   • Comment text (bodyText)
   • Author (author.login)
3. Address each unresolved comment by:
   • Locating the relevant code section
   • Making the requested changes
   • Ensuring the fix addresses the concern raised
4. Do NOT process resolved comments - they have already been handled

Example: Compact List of Unresolved Comments

For a quick overview of unresolved comments:

gh api graphql -F owner=cozystack -F repo=cozystack -F pr=<PR_NUMBER> -f query='
query($owner: String!, $repo: String!, $pr: Int!) {
  repository(owner: $owner, name: $repo) {
    pullRequest(number: $pr) {
      reviewThreads(first: 100) {
        nodes {
          isResolved
          comments(first: 100) {
            nodes {
              path
              line
              author { login }
              bodyText
            }
          }
        }
      }
    }
  }
}' --jq '.data.repository.pullRequest.reviewThreads.nodes[] | select(.isResolved == false) | .comments.nodes[] | "\(.path):\(.line // "N/A") - \(.author.login): \(.bodyText[:150])"'

Important Notes

• REST API limitation: The REST endpoint /pulls/{pr}/reviews returns review summaries, not individual review comments. Use GraphQL API for accessing reviewThreads with isResolved status.
• Thread-based resolution: Comments are organized in threads. If a thread is resolved (isResolved: true), ignore all comments in that thread.
• Always filter: Never process comments from resolved threads, even if they appear in the results.

Example Workflow

# Get PR comments
gh pr view 1234 --comments

# Review comments and identify valid ones
# Make necessary changes to address valid comments
# ... edit files ...

# Show what was changed (but don't commit)
git status
git diff

# Tell the user what was fixed and what was skipped

Git Permissions

Request these permissions when needed:

• git_write - For commit, rebase, cherry-pick, branch operations
• network - For push, fetch, pull operations

Common Issues

PR has extra commits?
→ Rebase on upstream/main and cherry-pick only your commits

Wrong commit message?
→ git commit --amend --signoff -m "[correct] message" then git push -f

Need to update PR?
→ gh pr edit <number> --body "new description"