playbooks

home / skills / jetbrains / ideavim / git-workflow

git-workflow skill

/.claude/skills/git-workflow

This skill guides git workflow in IdeaVim projects, enforcing branch, commit, and PR practices to maintain clean history and reliable releases.

npx playbooks add skill jetbrains/ideavim --skill git-workflow

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
1.7 KB
---
name: git-workflow
description: IdeaVim git workflow conventions covering commits, branches, PRs, and CI. Use when creating commits, managing branches, creating pull requests, reviewing git history, or any git-related activity in the IdeaVim project.
---

# Git Workflow

## Branching

- **Master** is the trunk and MUST always be in a "ready to release" state
- Use **feature branches** for development work
  - Naming: `VIM-XXXX/short-description` (e.g., `VIM-3948/editor`)
  - Rebase to master frequently to avoid large conflicts
- Small, isolated changes (bug fixes, minor tweaks) MAY go directly to master
- Unfinished changes MAY be committed to master only if they do NOT break functionality
- Use **rebase** for integration, not merge commits (linear history)

## Commits

**Standard format:**
```
VIM-XXXX Description of the change
```

- Start with the YouTrack ticket ID when the change relates to a ticket
- Example: `VIM-3948 Traverse vertical panes in ConfigurableEditor`

**Auto-closing format** (moves YouTrack ticket to "Ready To Release"):
```
fix(VIM-XXXX): Description of the fix
```

**Content rules:**
- Each commit MUST contain a single, focused, meaningful change
- MUST NOT include unrelated changes (formatting, unrelated refactoring)
- Include appropriate tests with behavioral changes

## Pull Requests

- PRs target `master`
- CI runs standard tests automatically (`./gradlew test -x :tests:property-tests:test -x :tests:long-running-tests:test`)
- PRs from external contributors are listed in the changelog under "Merged PRs"

## Issue Tracking

- Use **YouTrack** (not GitHub Issues) - tickets are `VIM-XXXX`
- URL: https://youtrack.jetbrains.com/issues/VIM

Overview

This skill documents the IdeaVim git workflow conventions for commits, branches, pull requests, and CI. It codifies branch naming, commit message formats, rebase policy, and expectations for tests and PRs. Use it as a practical guide when working on IdeaVim code changes to keep history linear and master release-ready.

How this skill works

The workflow enforces a trunk-based master that must always be releasable. Development happens on feature branches named with the YouTrack ticket ID (VIM-XXXX/short-description) and is regularly rebased onto master to avoid large conflicts. Commits follow strict formats so ticket links and automated ticket transitions work, and CI runs the standard Gradle test suite for every PR targeting master.

When to use it

  • Creating a new feature or bugfix for IdeaVim
  • Opening a pull request or preparing a branch for review
  • Committing changes that relate to a YouTrack ticket
  • Rebasing or integrating work onto master to keep history linear
  • Running or validating CI test expectations before merging

Best practices

  • Keep master always in a ready-to-release state; only small, safe fixes may land directly
  • Create focused commits: one logical change per commit with tests for behavioral edits
  • Name branches with the YouTrack ticket ID: VIM-XXXX/short-description
  • Rebase frequently onto master; avoid merge commits to maintain a linear history
  • Use the auto-closing commit format (fix(VIM-XXXX): ...) to move tickets to Ready To Release

Example use cases

  • Start a VIM-3948/feature branch when implementing a new editor traversal behavior
  • Make a single-issue commit with message "VIM-3948 Traverse vertical panes in ConfigurableEditor" and include tests
  • Rebase your feature branch onto master to resolve conflicts before opening a PR
  • Open a PR targeting master; CI will run the standard Gradle tests automatically
  • Apply a small formatting or typo fix directly to master if it doesn’t alter functionality

FAQ

When is it acceptable to commit directly to master?

Only for very small, isolated changes that don’t break functionality, such as minor fixes or documentation tweaks. Larger or unfinished work must live on a feature branch.

Which commit format moves a YouTrack ticket to Ready To Release?

Use the auto-closing format: fix(VIM-XXXX): Description of the fix. That format is recognized for advancing ticket state.