docs: Clarify documentation for repository comment_strategy

[aThorp96]

📝 Description of the Change

Add a more general "controlling comment volume" section with Github and Gitlab subsections to clarify the shared semantics

👨🏻‍ Linked Jira

None

🔗 Linked GitHub Issue

Fixes #2270

🚀 Type of Change

• 🐛 Bug fix (fix:)
• ✨ New feature (feat:)
• 💥 Breaking change (feat!:, fix!:)
• 📚 Documentation update (docs:)
• ⚙️ Chore (chore:)
• 💅 Refactor (refactor:)
• 🔧 Enhancement (enhance:)
• 📦 Dependency update (deps:)

🧪 Testing Strategy

• Unit tests
• Integration tests
• End-to-end tests
• Manual testing
• Not Applicable

🤖 AI Assistance

• I have not used any AI assistance for this PR.
• I have used AI assistance for this PR.

If you have used AI assistance, please provide the following details:

Which LLM was used?

• GitHub Copilot
• ChatGPT (OpenAI)
• Claude (Anthropic)
• Cursor
• Gemini (Google)
• Other: ____________

Extent of AI Assistance:

• Documentation and research only
• Unit tests or E2E tests only
• Code generation (parts of the code)
• Full code generation (most of the PR)
• PR description and comments
• Commit message(s)

Important

If the majority of the code in this PR was generated by an AI, please add a Co-authored-by trailer to your commit message.
For example:

Co-authored-by: Gemini gemini@google.com
Co-authored-by: ChatGPT noreply@chatgpt.com
Co-authored-by: Claude noreply@anthropic.com
Co-authored-by: Cursor noreply@cursor.com
Co-authored-by: Copilot Copilot@users.noreply.github.com

**💡You can use the script ./hack/add-llm-coauthor.sh to automatically add
these co-author trailers to your commits.

✅ Submitter Checklist

• 📝 My commit messages are clear, informative, and follow the project's How to write a git commit message guide. The Gitlint linter ensures in CI it's properly validated
• ✨ I have ensured my commit message prefix (e.g., fix:, feat:) matches the "Type of Change" I selected above.
• ♽ I have run make test and make lint locally to check for and fix any
  issues. For an efficient workflow, I have considered installing
  pre-commit and running pre-commit install to
  automate these checks.
• 📖 I have added or updated documentation for any user-facing changes.
• 🧪 I have added sufficient unit tests for my code changes.
• 🎁 I have added end-to-end tests where feasible. See README for more details.
• 🔎 I have addressed any CI test flakiness or provided a clear reason to bypass it.
• If adding a provider feature, I have filled in the following and updated the provider documentation:
  • GitHub App
  • GitHub Webhook
  • Gitea/Forgejo
  • GitLab
  • Bitbucket Cloud
  • Bitbucket Data Center

Closes #2278

[pipelines-as-code]

🔍 PR Lint Feedback

Note: This automated check helps ensure your PR follows our contribution guidelines.

⚠️ Items that need attention:

🤖 AI attribution

The following commits lack an explicit AI attribution footer:

• 3fbfaad docs: Clarify documentation for repository comment_strategy``

If no AI assistance was used for a commit, you can ignore this warning.
Otherwise add an Assisted-by: or Co-authored-by: footer referencing the AI used.

---

ℹ️ Next Steps

• Review and address the items above
• Push new commits to update this PR
• This comment will be automatically updated when issues are resolved

🔧 Admin Tools (click to expand)

Automated Issue/Ticket Creation:

• /issue-create - Generate a GitHub issue from this PR content using AI
• /jira-create - Create a SRVKP Jira ticket from this PR content using AI

⚠️ Important: Always review and edit generated content before finalizing tickets/issues.
The AI-generated content should be used as a starting point and may need adjustments.

These commands are available to maintainers and will post the generated content as PR comments for review.

_{🤖 This feedback was generated automatically by the PR CI system}

[chmouel]

/gemini review

[gemini-code-assist]

Code Review

This pull request does a great job of refactoring the documentation for the comment_strategy setting. Consolidating the information for GitHub and GitLab into a shared section significantly improves clarity and reduces duplication. I have a couple of minor suggestions to enhance the grammar and maintain consistency with the rest of the document.

[chmouel]

See the minor spell if you want to fix and it's GTG for me

[chmouel]

/issue-create

[pipelines-as-code]

✅ GitHub Issue Created

AI-generated issue has been created and linked to this PR

📋 Created Issue

#2278 - Feature Request: Clarify documentation on controlling comment volume for Git providers

🔗 Relationship

This pull request resolves the issue described above. The issue was automatically generated based on the PR content to represent the underlying problem being solved.

📝 Issue Content Preview

Click to view the generated issue content

Problem Description

Users need a clearer understanding of how to manage and control the volume of automated comments generated by the system across different Git providers like GitHub and GitLab.

Current Behavior

The existing documentation on repository settings, specifically comment_strategy, may be difficult to interpret or lacks sufficient detail to fully grasp the shared semantics and practical implications for controlling comment volume across various Git platforms.

Expected Behavior

The documentation should provide a comprehensive and easy-to-understand explanation of how to configure and manage the comment_strategy setting to effectively control the amount of automated commenting on repositories, with clear guidance tailored for both GitHub and GitLab environments.

Additional Context

This clarity is important for users who want to fine-tune the system's interaction with their repositories, preventing excessive or unwanted comments and ensuring a more streamlined workflow.

---

_{🤖 Issue created automatically using /issue-create command}

[chmouel]

i think it may be better to just set things as ready for review, I don't think it's necessary to do a draft pr or this would be confusing when to merge

[aThorp96]

AH, didn't realize I created this as a draft. Must have been a cached setting 🤔 Marked as ready for review 🙇🏼