Repository navigation
docs: add repository merge policy and safe issue/PR handling guidelines - #308
Conversation
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Summary of Changes
Hello @apstndb, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!
This pull request enhances the project's documentation by clarifying critical operational guidelines for repository management and content submission. It addresses past merge failures by explicitly stating the repository's "squash merge only" policy and improves developer experience by providing a robust method for safely handling special characters in issue and PR content, ensuring smoother workflows and more reliable automated processes.
Highlights
- Repository Merge Policy: Documented that this repository enforces a "squash merge only" policy via GitHub Repository Ruleset. This explicitly guides AI assistants and other automated processes to use the
squashmethod for all merges, preventing errors like those encountered in issue #307. - Safe Issue/PR Handling: Added guidance for creating and updating GitHub issues and pull requests, specifically recommending the use of
--body-file. This method helps to safely handle content containing special characters (such as backticks and quotes) and avoids common shell escaping issues.
Using Gemini Code Assist
The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.
Invoking Gemini
You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.
| Feature | Command | Description |
|---|---|---|
| Code Review | /gemini review |
Performs a code review for the current pull request in its current state. |
| Pull Request Summary | /gemini summary |
Provides a summary of the current pull request in its current state. |
| Comment | @gemini-code-assist | Responds in comments when explicitly tagged, both in issue comments and review comments. |
| Help | /gemini help |
Displays a list of available commands. |
Customization
To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.
Limitations & Feedback
Gemini Code Assist is currently in preview and may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments to provide feedback.
You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.
Footnotes
-
Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩
6a2d0d9 to
a7e2559
Compare
There was a problem hiding this comment.
Code Review
This PR adds valuable documentation to CLAUDE.md regarding the mandatory squash merge policy and a best practice for safely handling special characters in GitHub issues and PRs using --body-file. These changes are clear, well-justified, and crucial for AI assistants and developers interacting with the repository. I've included one suggestion to further clarify the scope of special characters for the AI audience, aiming to prevent potential misinterpretations.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
a7e2559 to
0e9124a
Compare
apstndb
added
the
ignore-for-release
This comment has been minimized.
This comment has been minimized.
- Add critical note about squash-only merge policy enforced by Repository Ruleset - Add comprehensive guidance for safe handling of special characters in shell commands - Recommend variable + stdin approach to avoid temporary files - Document tmp/ directory usage when temp files are necessary - Add ignore-for-release label usage guidelines for CLAUDE.md and dev-docs changes - Addresses issue #307 merge failures and shell escaping problems Fixes #307
0e9124a to
dbea1d2
Compare
This comment has been minimized.
This comment has been minimized.
- Add guideline to preserve review history by not rewriting pushed commits - Emphasize that explicit permission is required for any push --force operations - Important for maintaining integrity of code review process
This comment has been minimized.
This comment has been minimized.
- Address Gemini review feedback for broader interpretation - Include additional examples (dollar signs, parentheses) to emphasize comprehensiveness - Helps AI assistants understand this is not an exhaustive list
Code Metrics Report
Details | | main (fe08b20) | #308 (d216278) | +/- |
|---------------------|----------------|----------------|------|
| Coverage | 64.5% | 64.5% | 0.0% |
| Files | 30 | 30 | 0 |
| Lines | 3447 | 3447 | 0 |
| Covered | 2226 | 2226 | 0 |
| Code to Test Ratio | 1:0.6 | 1:0.6 | 0.0 |
| Code | 8334 | 8334 | 0 |
| Test | 5814 | 5814 | 0 |
+ | Test Execution Time | 1m31s | 1m10s | -21s |Reported by octocov |
|
/gemini review |
1 similar comment
|
/gemini review |
There was a problem hiding this comment.
Code Review
This pull request adds valuable documentation regarding the repository's merge policy and safe handling of special characters in shell commands. It also clarifies Git practices and the use of the ignore-for-release label. The changes are clear, accurate, and directly address the problems outlined in issue #307. I found no issues of high or critical severity; the documentation enhancements are well-implemented and beneficial.
There was a problem hiding this comment.
Code Review
This pull request adds critical documentation to CLAUDE.md and dev-docs/issue-management.md, covering repository merge policy, safe issue/PR handling, and Git practices. The changes enhance AI assistant reliability, content safety, and developer experience. The suggestions provided aim to further improve clarity and provide additional context for users.
Summary
This PR adds critical documentation to CLAUDE.md to address issue #307:
--body-fileto safely handle special characters in issue/PR contentChanges Made
🚨 CRITICAL REQUIREMENTS Section
squashmethod for automated mergesGitHub Issues/PRs Workflow Section
--body-fileapproach to avoid shell escaping issues with special charactersProblem Solved
Issue #307: When attempting to merge PR #306 using GitHub API with
merge_method: "merge", we encountered:Root Cause: Repository Ruleset "default branch" restricts
allowed_merge_methodsto["squash"]only.Additional Issue: Shell escaping problems when creating/updating issues with special characters (backticks, quotes) in content.
Impact
Validation
Fixes #307