| name | version-control |
| description | Best practices and rules for Git version control, branch management, pull requests, and commit/PR descriptions. |
Git & Version Control Guidelines
This skill defines the mandatory workflow rules and formatting requirements for managing source code history, branching, and pull requests in this repository.
1. Branching & Commit Workflow
- Dedicated Branches: All development work must occur on a dedicated feature branch created off of the
master branch.
- No Direct Commits: Under no circumstances should commits be pushed directly to the
master branch, unless explicitly and directly ordered by the user.
- Continuous Integration (CI): We use GitHub CI on our Pull Requests. A Pull Request must not be merged under any circumstances unless all CI checks pass successfully.
- Squash and Merge Only: We only squash and merge PRs when merging changes into the
master branch. Other merge strategies (e.g., rebase merge or merge commit) are forbidden.
- Pruning Remote Branches: Immediately after a Pull Request is successfully squashed and merged, the development branch must be deleted from the remote repository.
- Rationale:
- Critical files (e.g.,
release/setup.sh) have an immediate public-facing impact when merged to master. Dedicated branches and CI enforcement prevent accidental deployment of untested or broken changes.
- Pull Requests act as the primary review gate to keep the
master branch history clean, atomic, and organized.
2. Pull Request Format & Descriptions
When creating and editing Pull Requests, follow the Google Engineering Practices for CL Descriptions. The PR description acts as a permanent record of the change.
A. The Title (First Line)
Treat the PR title as the "first line of a CL description":
- Summarize What is Done: Provide a short, focused summary of specifically what is being done by the change. It should be informative enough for future code searchers to skim through history without opening the full PR.
- Write as an Imperative Command: Formulate it as a complete sentence written as though it was an order or instruction (e.g.,
Delete the widget API instead of Deleted the widget API or Deletes the widget API).
- Do Not Use Prefix Tags: Never prefix PR description titles with labels like
feat:, chore:, fix:, or docs:.
- Separate with Empty Line: Always leave a blank line between the title and the body of the description.
B. The Description Body
The description body must communicate the What and Why of the change in detail:
- The "What": Summarize the major changes so that readers can understand what is being modified without reading the entire diff.
- The "Why": Explain the problem being solved and why this specific approach was chosen. Document the developer's context, including decisions made that are not directly visible in the source code.
- Prevent Regressions (Chesterton's Fence): Explain why code is being introduced or changed so future engineers understand why it exists and don't accidentally break or remove it.
- Metadata & References: Include any relevant issue numbers, links to design documents, or test/benchmark results at the bottom of the body.
