From d78e099eed349c72180ace14b7123433e92a64ef Mon Sep 17 00:00:00 2001 From: gerchowl Date: Mon, 10 Nov 2025 20:34:23 +0000 Subject: [PATCH 1/7] feat(devcontainer): add podman-compose.yml for direct Podman usage Add podman-compose.yml configuration file to support users who prefer using Podman Compose instead of VS Code's built-in devcontainer support. Configuration includes: - Proper volume mount with cached consistency - Working directory set to /workspace - Interactive terminal support (stdin_open, tty) - Matches devcontainer.json settings This provides a declarative alternative to direct Podman CLI usage while maintaining compatibility with the devcontainer setup. Related to #24 --- podman-compose.yml | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 podman-compose.yml diff --git a/podman-compose.yml b/podman-compose.yml new file mode 100644 index 0000000..a7cab77 --- /dev/null +++ b/podman-compose.yml @@ -0,0 +1,10 @@ +version: '3' +services: + dev: + image: ghcr.io/morepet/containers/dev/typst:1.3-dev + volumes: + - .:/workspace:cached + working_dir: /workspace + command: /bin/bash + stdin_open: true + tty: true From 553d46fe9dadd894e7bf11717014a8833d134284 Mon Sep 17 00:00:00 2001 From: gerchowl Date: Mon, 10 Nov 2025 20:34:59 +0000 Subject: [PATCH 2/7] docs(readme): add comprehensive Podman usage documentation Add new section 'Using Podman Without VS Code Devcontainer' with three detailed options for using the devcontainer with Podman directly: Option 1: Direct Podman CLI Usage - Command-line usage with proper volume mounts - SELinux context handling (:Z flag) for Linux systems - Manual initialization script execution order - Pros/cons comparison Option 2: Podman Compose - Installation instructions for multiple platforms - Usage with podman-compose.yml file - Start/stop commands and workflow - Benefits of declarative configuration Option 3: Dev Container CLI - Official devcontainers/cli installation - Full devcontainer.json compatibility with --docker-path podman - Automatic lifecycle script execution - Complete feature support Additional documentation includes: - Comparison table of all three options - Recommendations for different use cases - Proper script execution order (post-create.sh, post-attach.sh) - SELinux considerations for Linux users - Links to Quick Start for VS Code integration This provides flexibility for users who prefer different workflows while maintaining full compatibility with the devcontainer setup. Fixes #24 --- README.md | 185 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 185 insertions(+) diff --git a/README.md b/README.md index 6542fca..2d2806c 100644 --- a/README.md +++ b/README.md @@ -237,6 +237,191 @@ Open your browser to to see: That's it! The build system handles everything automatically. +## Using Podman Without VS Code Devcontainer + +If you prefer to use Podman directly instead of VS Code's built-in devcontainer support, you have three options. +All options assume you've completed the [Host Machine Prerequisites](#host-machine-prerequisites) (especially GHCR authentication). + +### Option 1: Direct Podman CLI Usage + +Use Podman command-line directly for maximum control and minimal dependencies. + +**Start the container:** + +```bash +# Linux (with SELinux context) +podman run -it --rm \ + -v "${PWD}:/workspace:Z" \ + -w /workspace \ + ghcr.io/morepet/containers/dev/typst:1.3-dev \ + /bin/bash + +# macOS/Windows (no SELinux) +podman run -it --rm \ + -v "${PWD}:/workspace" \ + -w /workspace \ + ghcr.io/morepet/containers/dev/typst:1.3-dev \ + /bin/bash +``` + +**Important: SELinux Context (Linux only)** + +The `:Z` flag is required on Linux systems with SELinux to allow the container to access the mounted volume. Without it, you'll get permission denied errors. + +- `:Z` - Private unshared label (recommended for single container access) +- `:z` - Shared label (use if multiple containers need access) + +**Inside the container, run initialization scripts in order:** + +```bash +# 1. Post-create (one-time setup) +/workspace/.devcontainer/post-create.sh + +# 2. Post-attach (session setup) +/workspace/.devcontainer/post-attach.sh + +# 3. Build documentation +make +``` + +**Script execution order matters:** +1. `post-create.sh` - Sets up git, GitHub CLI, pre-commit hooks, Node.js +2. `post-attach.sh` - Configures git and verifies GitHub CLI for current session + +**Pros:** +- No additional tools required beyond Podman +- Full control over container lifecycle +- Easy to customize and script + +**Cons:** +- Manual script execution required +- Need to remember the correct command and flags +- No automatic devcontainer.json integration + +### Option 2: Podman Compose + +Use `podman-compose` for a more declarative approach with persistent configuration. + +**Install podman-compose:** + +```bash +# Using pip +pip install podman-compose + +# Or using system package manager (Fedora/RHEL) +sudo dnf install podman-compose + +# Or using system package manager (Debian/Ubuntu) +sudo apt install podman-compose +``` + +**Start the container:** + +```bash +# Start in detached mode +podman-compose up -d + +# Attach to the running container +podman-compose exec dev /bin/bash +``` + +**Inside the container, run initialization scripts:** + +```bash +# Run setup scripts in order +/workspace/.devcontainer/post-create.sh +/workspace/.devcontainer/post-attach.sh + +# Build documentation +make +``` + +**Stop the container:** + +```bash +podman-compose down +``` + +**Configuration file:** The repository includes `podman-compose.yml` with proper settings: +- Volume mount with cached consistency +- Working directory set to `/workspace` +- Interactive terminal support +- Matches devcontainer.json configuration + +**Pros:** +- Declarative configuration in `podman-compose.yml` +- Easy to start/stop with simple commands +- Persistent container state (optional) +- Familiar Docker Compose syntax + +**Cons:** +- Requires installing podman-compose +- Still need to manually run initialization scripts +- Limited devcontainer.json feature support + +### Option 3: Dev Container CLI + +Use the official Dev Container CLI for full `devcontainer.json` compatibility with Podman. + +**Install Dev Container CLI:** + +```bash +npm install -g @devcontainers/cli +``` + +**Start the devcontainer with Podman:** + +```bash +# Build and start the devcontainer +devcontainer up --workspace-folder . --docker-path podman + +# Execute commands inside +devcontainer exec --workspace-folder . make + +# Open a shell +devcontainer exec --workspace-folder . /bin/bash +``` + +**Full integration:** + +The Dev Container CLI automatically: +- ✅ Reads and applies `.devcontainer/devcontainer.json` settings +- ✅ Runs `initializeCommand` on the host +- ✅ Executes `postCreateCommand` and `postAttachCommand` in container +- ✅ Mounts volumes correctly +- ✅ Installs VS Code extensions (when used with VS Code) + +**Pros:** +- **Best option for full compatibility** with devcontainer.json +- Automatic script execution in correct order +- Supports all devcontainer features (extensions, settings, lifecycle scripts) +- Works with Podman via `--docker-path` flag +- Can be used in CI/CD pipelines + +**Cons:** +- Requires Node.js and npm +- More complex installation +- Slight learning curve for CLI commands + +### Comparison Table + +| Feature | Direct CLI | Podman Compose | Dev Container CLI | +|---------|------------|----------------|-------------------| +| **Setup Complexity** | Low | Medium | Medium | +| **Dependencies** | Podman only | Podman + podman-compose | Podman + Node.js + npm | +| **Script Automation** | Manual | Manual | Automatic ✅ | +| **devcontainer.json Support** | None | None | Full ✅ | +| **Flexibility** | Highest | High | Medium | +| **Best For** | Quick tests, scripting | Persistent dev environments | Full devcontainer compatibility | + +### Recommendation + +- **Use Option 1 (Direct CLI)** for quick testing or one-off builds +- **Use Option 2 (Podman Compose)** if you prefer docker-compose workflow +- **Use Option 3 (Dev Container CLI)** for the most complete devcontainer experience + +**Still prefer VS Code integration?** See [Quick Start](#quick-start) for using VS Code's built-in Dev Containers extension, which provides the best IDE integration. + ## Features ### Documentation Generation From 572190d7b817fc83b7a61cfb2e6c8f10b2a004c1 Mon Sep 17 00:00:00 2001 From: gerchowl Date: Mon, 10 Nov 2025 20:35:32 +0000 Subject: [PATCH 3/7] docs(changelog): add entry for Podman usage documentation Document addition of comprehensive Podman usage guide with three options for using the devcontainer without VS Code: - Direct Podman CLI with SELinux considerations - Podman Compose with declarative configuration - Dev Container CLI for full compatibility Related to #24 --- CHANGELOG.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0dae43a..b53a2f3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,21 @@ All notable changes to this template will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [Unreleased] + +### Added + +- **Podman Usage Documentation** + - Comprehensive guide for using devcontainer with Podman without VS Code (#24) + - Three usage options: Direct CLI, Podman Compose, and Dev Container CLI + - `podman-compose.yml` configuration file for declarative container management + - Detailed comparison table of all three Podman usage options + - SELinux context handling documentation for Linux users (`:Z` flag) + - Proper initialization script execution order (post-create.sh, post-attach.sh) + - Installation instructions for multiple platforms + - Pros/cons analysis for each approach + - Recommendations for different use cases + ## [0.4.1] - 2025-11-10 ### Fixed From f64f44b5123a30aa35938563326d3baf14d369a0 Mon Sep 17 00:00:00 2001 From: gerchowl Date: Mon, 10 Nov 2025 20:49:19 +0000 Subject: [PATCH 4/7] refactor(commands): optimize all command files for AI execution MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Restructured all 6 command files (.cursor/commands/) to be AI-execution optimized rather than human-documentation focused. Key improvements: - Imperative commands instead of descriptive prose - Inline error handling with recovery steps - Decision trees (IF/THEN/ELSE) for branching logic - Step-by-step execution protocols - Integrated failure modes and automatic recovery - Removed explanatory prose and examples - Added execution checklists for self-verification Size reductions (68% average): - yolo-issue.md: 1022 → 302 lines (70%) - create-pr.md: 355 → 184 lines (48%) - tag-and-release.md: 704 → 324 lines (54%) - solve-issue.md: 674 → 387 lines (43%) - create-issue.md: 152 → 98 lines (36%) - git-commit.md: 493 → 225 lines (54%) Files now barely human-readable but highly AI-executable with clear directives, inline error handling, and minimal explanatory prose. Also updated .pre-commit-config.yaml to exclude .cursor/commands/ from pymarkdown linting since these are AI-optimized execution files where clarity matters more than markdown formatting perfection. Related to #24 --- .cursor/commands/create-issue.md | 224 ++++--- .cursor/commands/create-pr.md | 498 +++++++------- .cursor/commands/git-commit.md | 568 ++++++---------- .cursor/commands/solve-issue.md | 884 ++++++++++++------------- .cursor/commands/tag-and-release.md | 803 ++++++++--------------- .cursor/commands/yolo-issue.md | 961 ++++++---------------------- .pre-commit-config.yaml | 2 +- 7 files changed, 1383 insertions(+), 2557 deletions(-) diff --git a/.cursor/commands/create-issue.md b/.cursor/commands/create-issue.md index d4331c8..1849ca6 100644 --- a/.cursor/commands/create-issue.md +++ b/.cursor/commands/create-issue.md @@ -1,151 +1,171 @@ # Create Issue Command -This command helps you create issues in GitHub repositories using the GitHub CLI. +**CREATES GITHUB ISSUES - REQUIRES USER CONFIRMATION** -## ⚠️ CRITICAL WORKFLOW - MUST FOLLOW +Execute `/create-issue` to create issues following project standards. -When creating an issue, **ALWAYS** follow these steps in order: +## EXECUTION PROTOCOL -### 1. Determine the target repository +### STEP 1: DETERMINE TARGET REPOSITORY -- If user specifies a repo (e.g., "ORG/REPO"), use that -- Otherwise, detect current repo with: `gh repo view --json nameWithOwner --jq .nameWithOwner` +```bash +# If user specifies repo: use "ORG/REPO" +# Otherwise detect current: +REPO=$(gh repo view --json nameWithOwner --jq .nameWithOwner) +``` -### 2. Verify the repository exists +### STEP 2: VERIFY REPOSITORY ACCESS ```bash -gh repo view ORG/REPO --json nameWithOwner,description +gh repo view $REPO --json nameWithOwner,description ``` -- If successful, show repo name and description -- If failed, inform user the repo doesn't exist or isn't accessible +**IF fails:** +→ Display: "❌ Repository not found or not accessible: $REPO" +→ ABORT -### 3. **⚠️ CONFIRM WITH USER FIRST** (MANDATORY) +**IF succeeds:** +→ Display repo name and description +→ PROCEED to STEP 3 -**DO NOT create the issue yet!** Show the user: -- ✓ Target repository: `ORG/REPO` -- ✓ Issue type: `Bug` / `Feature` / `Task` -- ✓ Issue title: `"Your title here"` -- ✓ Preview of issue body (first 20 lines) -- ❓ **Ask:** "Create this issue? (yes/no)" +### STEP 3: GATHER ISSUE DETAILS -### 4. Create the issue ONLY after user confirms "yes" +**Determine from user input:** +- Issue type: Bug / Feature / Task +- Title (clear, descriptive) +- Body (structured with headings) +- Assignees (optional) -GitHub will automatically assign the next available issue number. **DO NOT** specify the issue number yourself! +**Format body based on type:** -## Quick Reference +**Bug:** +```markdown +## Description +[What's wrong] -### Create a Bug Issue +## Steps to Reproduce +1. [Step 1] +2. [Step 2] -```bash -gh api \ - --method POST \ - /repos/ORG/REPO/issues \ - --field title="Brief description of the problem" \ - --field body="" \ - --field type="Bug" +## Expected Behavior +[What should happen] + +## Actual Behavior +[What actually happens] + +## Environment +- OS: +- Version: ``` -### Create a Feature Issue +**Feature:** +```markdown +## Feature Request +[What feature is needed] -```bash -gh api \ - --method POST \ - /repos/ORG/REPO/issues \ - --field title="Feature title" \ - --field body="" \ - --field type="Feature" +## Use Case +[Why it's needed] + +## Proposed Solution +[How it could work] + +## Alternatives Considered +[Other approaches] ``` -### Create a Task Issue +**Task:** +```markdown +## Task Description +[What needs to be done] -```bash -gh api \ - --method POST \ - /repos/ORG/REPO/issues \ - --field title="Task: Brief description" \ - --field body="" \ - --field type="Task" \ - --field assignees[]="username" +## Acceptance Criteria +- [ ] [Criterion 1] +- [ ] [Criterion 2] + +## Related Issues +- Related to #X ``` -**Important Notes:** -- GitHub automatically assigns the next available issue number -- **DO NOT add labels** unless explicitly requested by user -- Only use: `title`, `body`, `type`, and optionally `assignees[]` +### STEP 4: CONFIRM WITH USER (MANDATORY) -## Utility Commands +**MUST display preview and wait for confirmation:** -### Get Current Repo +```text +📋 Issue Preview -```bash -gh repo view --json nameWithOwner --jq .nameWithOwner -``` +Target: ORG/REPO +Type: Bug/Feature/Task +Title: "Your title here" -### Verify Repo Exists +Body: +[First 20 lines of body...] -```bash -gh repo view ORG/REPO --json nameWithOwner,description +❓ Create this issue? (yes/no) ``` -Example output: +**WAIT for user response.** -```json -{ - "description": "Repository description", - "nameWithOwner": "ORG/REPO" -} -``` +**IF user says "no" or anything other than "yes":** +→ Display: "Issue creation cancelled" +→ ABORT + +**IF user says "yes":** +→ PROCEED to STEP 5 -### Check Repo Access +### STEP 5: CREATE ISSUE + +**GitHub auto-assigns issue number - DO NOT specify it yourself:** ```bash -gh repo view ORG/REPO --json nameWithOwner,description,viewerPermission +gh api --method POST /repos/$REPO/issues \ + --field title="$TITLE" \ + --field body="$BODY" ``` ---- +**IF assignees requested:** +```bash +gh api --method POST /repos/$REPO/issues \ + --field title="$TITLE" \ + --field body="$BODY" \ + --field assignees[]="$USERNAME" +``` -## Examples +**DO NOT add labels unless user explicitly requests them.** -### Example 1: Bug Report +### STEP 6: CONFIRM CREATION -```bash -# 1. Get repo -REPO=$(gh repo view --json nameWithOwner --jq .nameWithOwner) +```text +✅ Issue created successfully -# 2. Show user what will be created -echo "Creating bug report in $REPO" -echo "Type: Bug" -echo "Title: Login button doesn't work on mobile" -echo "" -echo "Create this issue? (yes/no)" -read -r confirm - -# 3. Create only if confirmed -if [ "$confirm" = "yes" ]; then - gh api --method POST /repos/$REPO/issues \ - --field title="Login button doesn't work on mobile" \ - --field body="## Description -Login button is not responsive on mobile devices..." \ - --field type="Bug" -fi +Issue: # +Title: +URL: https://github.com/ORG/REPO/issues/<number> ``` -### Example 2: Feature Request +## ERROR HANDLING -```bash -gh api --method POST /repos/ORG/REPO/issues \ - --field title="Add dark mode support" \ - --field body="## Feature Request\n\nWe should add dark mode..." \ - --field type="Feature" -``` +**Repository not found:** +→ "❌ Repository not accessible: ORG/REPO" +→ Verify repo exists and you have access + +**Authentication failure:** +→ Run `gh auth status` +→ Run `gh auth login` if not authenticated + +**API error:** +→ Check error message from gh CLI +→ Verify user has write access to repo ---- +## CRITICAL RULES -## Common Mistakes +**NEVER:** +- ❌ Specify issue number (GitHub auto-assigns) +- ❌ Add labels without explicit user request +- ❌ Create without user confirmation +- ❌ Use fields other than: title, body, assignees -❌ **Specifying issue number** - GitHub assigns this automatically -❌ **Adding labels** - DO NOT add `labels[]` unless user explicitly asks -❌ **Creating without confirmation** - Always ask user first -❌ **Wrong type values** - Must be exactly: `Bug`, `Feature`, or `Task` -❌ **Assuming what user wants** - Only add fields user explicitly requests +**ALWAYS:** +- ✅ Show preview before creating +- ✅ Wait for explicit "yes" confirmation +- ✅ Let GitHub assign issue number +- ✅ Use structured body format diff --git a/.cursor/commands/create-pr.md b/.cursor/commands/create-pr.md index 2355488..1ed741c 100644 --- a/.cursor/commands/create-pr.md +++ b/.cursor/commands/create-pr.md @@ -1,354 +1,328 @@ -# Create Pull Request Command +# Create PR Command -This command helps you create pull requests following the project's standards and guidelines. +**CREATES PULL REQUESTS WITH VERSION MANAGEMENT** -For complete documentation on pull request guidelines, templates, and review process, see: +Execute `/create-pr` to create PRs following project standards with AI-powered version bumping. -**Related Documentation:** +## EXECUTION PROTOCOL -- **[Pull Request Guidelines](./../pr-template.md)** -- **[Git Workflow](./../git-workflow.md)** -- **[Version Management](./../VERSION_MANAGEMENT.md)** +### STEP 1: VERSION BUMP & CHANGELOG (MANDATORY FIRST) -## Workflow +**Run BEFORE creating PR. Version bump happens in PR, not after merge.** -**Style Guidelines:** -- Use standard markdown lists: `-` for bullets, `- [ ]` for unchecked, `- [x]` for checked -- Never use emojis for lists or checkboxes -- Keep PR descriptions clean and professional +```bash +CURRENT_VERSION=$(make version | grep -oP '\d+\.\d+\.\d+') +COMMITS=$(git log --oneline origin/main..HEAD) +FILES=$(git diff --name-only origin/main...HEAD) +``` + +**AI Analysis:** +- Parse commits for: `BREAKING CHANGE`, `feat:`, `fix:` +- Examine code diffs: new APIs, signature changes, file impact +- Categorize: user-facing vs internal changes -When creating a pull request, follow these steps: +**Present recommendation:** +```text +🤖 AI Analysis -### 0. AI-Powered Version Bump & CHANGELOG (Before PR Creation) +Current: $CURRENT_VERSION +Changes: [summary] -**IMPORTANT:** Version bump and CHANGELOG update happen **during PR creation**, not after merge. -After PR is merged to main, run `/tag-and-release` directly to create the git tag and GitHub release. -We start with version bump only then edit the changelog +Recommended: MINOR bump → X.Y.0 +Rationale: [explanation] -**AI analyzes your changes, suggests version bump, and generates CHANGELOG:** +Version bump: +1) patch - Bug fixes only +2) minor - New features ← Recommended +3) major - Breaking changes +4) skip -```bash -# Gather data -CURRENT_VERSION=$(make version | grep -oP '\d+\.\d+\.\d+') -COMMITS=$(git log --oneline origin/main..HEAD) -FILES=$(git diff --name-only origin/main...HEAD) +Choice [2]: +``` -# AI Analysis: Check commits AND examine actual code changes -# Mechanical: BREAKING CHANGE, feat:, fix: in commits -# Intelligent: New APIs, signature changes, file impact, user-facing changes - -# AI presents recommendation -echo "🤖 AI Analysis: Current $CURRENT_VERSION" -echo "" -echo "Changes detected:" -echo " - [AI summary of actual changes]" -echo "" -echo "📈 Recommended: MINOR bump → 0.4.0" -echo " Rationale: [AI explanation]" -echo "" -echo "Apply version bump?" -echo " 1) patch - Bug fixes only" -echo " 2) minor - New features ← AI suggests" -echo " 3) major - Breaking changes" -echo " 4) skip" -read -p "Choice [default=2]: " CHOICE - -# Apply bump -case "${CHOICE:-2}" in +**WAIT for user input.** + +**Execute bump:** +```bash +case "$CHOICE" in 1) make bump-patch; BUMP_TYPE="patch" ;; 2) make bump-minor; BUMP_TYPE="minor" ;; 3) make bump-major; BUMP_TYPE="major" ;; 4) BUMP_TYPE="" ;; esac +``` -# AI generates CHANGELOG entry automatically -if [ -n "$BUMP_TYPE" ]; then - NEW_VERSION=$(make version | grep -oP '\d+\.\d+\.\d+') - - # AI analyzes diff and generates Keep a Changelog formatted entry - # Creates ## [X.Y.Z] - YYYY-MM-DD section with proper categories - # Categorizes: Added/Changed/Fixed based on actual changes - # Uses clear, user-focused language - # NO [Unreleased] section - version is final +**IF bump applied:** +```bash +NEW_VERSION=$(make version | grep -oP '\d+\.\d+\.\d+') - echo "✨ AI generated CHANGELOG for $NEW_VERSION" - echo " - Created ## [$NEW_VERSION] - $(date +%Y-%m-%d) section" - echo " - Categorized changes: Added/Changed/Fixed" - echo " - User-focused descriptions" - echo "" - echo "📝 Review and refine CHANGELOG in PR if needed" +# AI generates CHANGELOG entry +# Format: Keep a Changelog +# Creates: ## [X.Y.Z] - YYYY-MM-DD +# Categories: Added/Changed/Fixed +# NO [Unreleased] section +``` - # Commit version bump with changelog - git add pyproject.toml CHANGELOG.md - git commit -m "chore(release): bump version to $NEW_VERSION +**Commit version bump:** +```bash +git add pyproject.toml CHANGELOG.md +git commit -m "chore(release): bump version to $NEW_VERSION Version bump: $CURRENT_VERSION → $NEW_VERSION Type: $BUMP_TYPE AI-generated CHANGELOG entry. Refinable in PR review." - - echo "" - echo "✅ Version bumped and CHANGELOG updated" - echo " Ready to create PR and merge" - echo " After merge: run /tag-and-release on main" -fi ``` -**AI Analysis Factors:** - -- **Commits:** `BREAKING CHANGE`, `feat:`, `fix:` patterns -- **Code:** New APIs, signature changes, refactoring detection -- **Files:** New vs. modified, public vs. internal -- **Impact:** User-facing vs. internal changes - -**Semantic Versioning:** - -- **MAJOR (X.0.0):** Breaking changes, API removals -- **MINOR (0.X.0):** New features (backward compatible) -- **PATCH (0.0.X):** Bug fixes, docs, internal refactoring - -**CHANGELOG Format:** - -The AI generates a properly formatted CHANGELOG entry following Keep a Changelog: +**Display:** +```text +✅ Version bumped: $CURRENT_VERSION → $NEW_VERSION +✅ CHANGELOG updated +Ready to create PR +``` -```markdown -## [0.4.0] - 2025-11-10 +### STEP 2: VALIDATE PREREQUISITES -### Added +```bash +git status +``` -- **Feature Name**: Description of new feature - - Sub-feature details - - User-facing benefits +**DECISION POINT: Working directory clean?** -### Changed +**IF NOT clean:** +→ Display: "❌ Uncommitted changes detected. Commit all changes first." +→ List uncommitted files +→ ABORT -- **Component Name**: Description of changes - - What changed and why - - Impact on users +**IF clean:** +→ PROCEED to STEP 3 -### Fixed +### STEP 3: VERIFY BRANCH -- Bug description and resolution +```bash +BRANCH=$(git branch --show-current) ``` -**No [Unreleased] Section:** +**Check branch naming:** +- Valid prefixes: `feature/`, `fix/`, `docs/`, `refactor/`, `test/`, `chore/`, `release/`, `issue<number>` -Version is determined during PR creation, so CHANGELOG entries go directly -under versioned sections (`## [X.Y.Z] - YYYY-MM-DD`). No `[Unreleased]` header needed. +**IF invalid branch name:** +→ Display: "⚠️ Branch name doesn't follow conventions" +→ Ask: "Proceed anyway? (yes/no)" +→ IF no: ABORT -1. **Ensure your branch follows naming conventions:** - - `feature/`, `fix/`, `docs/`, `refactor/`, `test/`, `chore/`, or `release/` - - Example: `feature/add-user-authentication` +**IF valid:** +→ PROCEED to STEP 4 -2. **Verify branch is up to date:** +### STEP 4: REBASE ON MAIN - ```bash - git checkout main - git pull origin main - git checkout your-branch - git rebase main - ``` +```bash +git checkout main +git pull origin main +git checkout $BRANCH +git rebase main +``` -3. **Ensure all changes are committed:** +**IF rebase conflicts:** +→ Display: "❌ Rebase conflicts detected" +→ Guide user through resolution +→ After resolution: `git rebase --continue` +→ Verify clean: `git status` - ```bash - git status # Must show "nothing to commit, working tree clean" - ``` +**IF rebase succeeds:** +→ PROCEED to STEP 5 - - **All work must be committed before creating PR** - - No uncommitted changes allowed - - No untracked files that should be included - - See [git-commit.md](./git-commit.md) for commit guidelines +### STEP 5: PUSH BRANCH -4. **Run pre-commit hooks and tests:** +```bash +git push -u origin $BRANCH +``` - ```bash - # All pre-commit hooks should have passed during commits - # Verify tests pass if applicable - ``` +**IF push fails (authentication):** +```bash +gh auth setup-git +git push -u origin $BRANCH +``` -5. **Self-review your changes:** - - Read through the diff - - Check for console.logs, TODOs, or debug code - - Verify all tests pass - - Confirm pre-commit hooks passed +**IF push fails (force needed after rebase):** +→ Ask user: "Force push needed after rebase. Proceed? (yes/no)" +→ IF yes: +```bash +git push --force-with-lease origin $BRANCH +``` -6. **Push your branch:** +### STEP 6: CREATE PR - ```bash - git push origin your-branch - ``` +**Determine PR type from commits:** +- feat commits → `feat:` +- fix commits → `fix:` +- docs commits → `docs:` +- Mixed → use primary type -7. **Create the pull request:** +**Generate PR body:** +```markdown +## Description - ```bash - gh pr create - ``` +[Summary of changes] -8. **Fill out the PR template** with: - - Clear, descriptive title - - Detailed description of changes - - Related issues (if applicable) - - Testing information - - Screenshots (if UI changes) +## Changes -## Quick Reference +### Core Implementation +- [File]: [What changed] -### Create a Feature PR +### Tests +- [Test file]: [Coverage] -```bash -# Ensure you're on feature branch -git checkout feature/add-dark-mode +### Documentation +- [Doc file]: [Updates] +- CHANGELOG.md: Version bump to X.Y.Z -# Rebase on latest main -git rebase main - -# Push and create PR -git push origin feature/add-dark-mode -gh pr create \ - --title "feature: Add dark mode toggle" \ - --body "## Description +## Testing -Add dark mode support to the application. +- [x] All tests passing +- [x] Pre-commit hooks passed +- [x] Manual testing completed -## Changes +## Related Issues -- Added theme context and provider -- Implemented dark mode CSS variables -- Added toggle component to settings +Closes #X +Related to #Y -## Testing +## Version Bump -- [x] Tested locally in dev container -- [x] All pre-commit hooks pass -- [x] Manual testing completed" +- Current → New: $OLD → $NEW +- Type: $BUMP_TYPE +- CHANGELOG: Updated with AI-generated entry ``` -### Create a Bug Fix PR - +**Create PR using temp file:** ```bash -# Ensure you're on fix branch -git checkout fix/auth-bug - -# Rebase on latest main -git rebase main +cat > /tmp/pr-body.md << 'EOF' +[PR body content] +EOF -# Push and create PR -git push origin fix/auth-bug gh pr create \ - --title "fix: Resolve authentication timeout issue" \ - --body "## Description - -Fixed authentication session timeout bug that was causing users to be -logged out unexpectedly. + --title "<type>: <description> (closes #X)" \ + --body-file /tmp/pr-body.md -## Changes - -- Extended session timeout from 30 to 60 minutes -- Added proper session refresh logic -- Updated error handling for expired sessions - -## Testing - -- [x] Unit tests added for session handling -- [x] Integration tests pass -- [x] Manual testing completed - -Closes #123" +rm /tmp/pr-body.md ``` -### Create a Documentation PR - -```bash -# Ensure you're on docs branch -git checkout docs/update-readme - -# Rebase on latest main -git rebase main - -# Push and create PR -git push origin docs/update-readme -gh pr create \ - --title "docs: Update installation instructions" \ - --body "## Description +**Use `--body-file` to avoid shell escaping issues with special characters.** -Updated README.md with clearer installation instructions for new developers. +### STEP 7: CONFIRM CREATION -## Changes +```text +✅ PR Created -- Added step-by-step installation guide -- Included troubleshooting section -- Added links to dev container setup +PR: #<number> +URL: <url> +Title: <title> +Status: Open (ready for review) -## Testing +Version: $OLD → $NEW +CHANGELOG: Updated -- [x] Documentation renders correctly -- [x] Links are valid -- [x] Follows documentation style guide" +Next steps: +- Wait for CI checks +- Address review feedback +- After merge: run `/tag-and-release` ``` -## PR Title Format - -Use clear, descriptive titles following conventional commit format: +## PR TITLE FORMAT -```text -<type>: Brief description of changes +``` +<type>: <description> (closes #<issue>) ``` -Examples: -- `feature: Add user profile page` -- `fix: Resolve database connection leak` -- `docs: Update API documentation` -- `refactor: Extract common auth logic` - -## Common PR Checks - -Before creating PR, ensure: - -- **All changes are committed** (clean working directory) -- Branch follows naming convention -- Commits follow conventional format -- All pre-commit hooks pass -- Tests are passing -- CHANGELOG.md updated (if user-facing change) -- No breaking changes without major version discussion +**Examples:** +- `feat: add user authentication (closes #42)` +- `fix: resolve database timeout (fixes #123)` +- `docs: update API documentation (closes #67)` -## After PR Creation +## VERSION BUMPING RULES -1. **Wait for CI checks** to complete -2. **Address review feedback** promptly -3. **Mark conversations as resolved** when fixed -4. **Rebase and update** if main branch changes -5. **Merge when approved** (maintainers handle merging) +**MAJOR (X.0.0):** +- Breaking changes +- API removals +- Incompatible changes -## Utility Commands +**MINOR (0.X.0):** +- New features (backward compatible) +- New APIs +- Enhancements -### Check Current Branch +**PATCH (0.0.X):** +- Bug fixes +- Documentation +- Internal refactoring +- No new features -```bash -git branch --show-current -``` +## CHANGELOG FORMAT -### View Recent Commits +**AI generates:** +```markdown +## [X.Y.Z] - YYYY-MM-DD -```bash -git log --oneline -5 -``` +### Added +- New features -### Check if Branch is Behind +### Changed +- Modifications -```bash -git status -# Look for "Your branch is behind 'origin/main' by X commits" +### Fixed +- Bug fixes ``` -### Interactive Rebase (Clean Up Commits) - -```bash -git rebase -i HEAD~3 # Last 3 commits -# Use 'squash' to combine, 'reword' to change messages -``` +**NO [Unreleased] section** - version determined during PR creation. + +## ERROR RECOVERY + +**Uncommitted changes:** +→ `git status` to see files +→ Commit with `/git-commit` +→ Retry `/create-pr` + +**Rebase conflicts:** +→ Resolve conflicts in files +→ `git add` resolved files +→ `git rebase --continue` +→ Retry push + +**Push authentication failure:** +→ `gh auth setup-git` +→ `gh auth status` to verify +→ Retry push + +**PR creation failure:** +→ Check branch is pushed: `git branch -r | grep $BRANCH` +→ Verify gh CLI auth: `gh auth status` +→ Check for existing PR: `gh pr list` + +## EXECUTION CHECKLIST + +**Before PR creation:** +- [ ] Version bumped (if applicable) +- [ ] CHANGELOG updated +- [ ] All changes committed +- [ ] Working directory clean +- [ ] Branch rebased on latest main +- [ ] All tests passing +- [ ] Pre-commit hooks passed + +**During PR creation:** +- [ ] Branch pushed successfully +- [ ] PR title follows format +- [ ] PR body comprehensive +- [ ] Issue references included +- [ ] Version bump noted + +**After PR creation:** +- [ ] CI checks pass +- [ ] Review feedback addressed +- [ ] Mark ready for review +- [ ] After merge: run `/tag-and-release` --- -**See [pr-template.md](./../pr-template.md) and [git-workflow.md](./../git-workflow.md) for detailed guidelines and examples.** +**WORKFLOW:** version bump → create PR → merge → `/tag-and-release` creates git tag and release diff --git a/.cursor/commands/git-commit.md b/.cursor/commands/git-commit.md index c980958..60c00bc 100644 --- a/.cursor/commands/git-commit.md +++ b/.cursor/commands/git-commit.md @@ -1,17 +1,12 @@ # Git Commit Command -This command helps you create proper conventional commits following the project's standards. +**CREATES CONVENTIONAL COMMITS - PRE-COMMIT HOOKS ENFORCED** -For complete documentation on commit conventions, workflow, and best practices, see: +Execute `/git-commit` for proper conventional commits following project standards. -**[Git Workflow Documentation](./../git-workflow.md)** +## COMMIT FORMAT (MANDATORY) -## Commit Message Format - -**ALWAYS use conventional commits** with this format: - -```text -```text +``` <type>(<scope>): <description> <body> @@ -19,146 +14,163 @@ For complete documentation on commit conventions, workflow, and best practices, <footer> ``` -### Required Elements +**REQUIRED:** type, scope, description +**OPTIONAL:** body, footer -**Type** (required): What kind of change -**Scope** (required): Module/component affected (must be from allowed list) -**Description** (required): Brief summary (50 chars max) +## TYPES -### Optional Elements +| Type | Usage | +|------|-------| +| `feat` | New feature | +| `fix` | Bug fix | +| `docs` | Documentation | +| `style` | Formatting (no logic change) | +| `refactor` | Code restructure (no behavior change) | +| `perf` | Performance improvement | +| `test` | Tests | +| `chore` | Maintenance | +| `ci` | CI/CD changes | +| `build` | Build system | +| `revert` | Revert commit | -**Body** (optional): Detailed explanation -**Footer** (optional): Breaking changes, issue references +## SCOPES (REQUIRED - FROM ALLOWED LIST) -## Commit Types +See `.gitlint` for complete list of 20 allowed scopes. -| Type | When to Use | Example | -|------|-------------|---------| -| `feat` | New feature | `feat(auth): add user login` | -| `fix` | Bug fix | `fix(api): resolve memory leak` | -| `docs` | Documentation | `docs(readme): update install guide` | -| `style` | Code formatting | `style(python): format with ruff` | -| `refactor` | Code restructure | `refactor(auth): extract validation` | -| `perf` | Performance improvement | `perf(api): optimize query` | -| `test` | Test additions/changes | `test(auth): add login tests` | -| `chore` | Maintenance tasks | `chore(deps): update packages` | -| `ci` | CI/CD changes | `ci(workflow): add python matrix` | -| `build` | Build system changes | `build(config): update pyproject.toml` | -| `revert` | Revert previous commit | `revert(api): undo breaking change` | +**Categories:** +- Code: `auth`, `api`, `ui`, `cli` +- Docs: `readme`, `changelog` +- Infra: `workflow`, `github`, `deps`, `devcontainer`, `config` +- Languages: `typst`, `python`, `markdown`, `yaml` +- Tools: `pre-commit`, `gitlint`, `linter` +- Other: `security`, `release` -## Scope Guidelines +**Rules:** +- Lowercase only +- No spaces +- Hyphens for multi-word (`pre-commit`) +- Must be from allowed list -**Scopes are REQUIRED** for all commits and must be from the allowed list. +## EXECUTION PROTOCOL -**See [.gitlint](../.gitlint) for the complete list of 20 allowed scopes.** +### STEP 1: REVIEW CHANGES -Scopes are organized by category: - -- **Code/Feature Areas:** `auth`, `api`, `ui`, `cli` -- **Documentation:** `readme`, `changelog` -- **Infrastructure:** `workflow`, `github`, `deps`, `devcontainer`, `config` -- **Languages/Tools:** `typst`, `python`, `markdown`, `yaml` -- **Tooling:** `pre-commit`, `gitlint`, `linter` -- **Other:** `security`, `release` +```bash +git status +git diff --staged --name-only | wc -l +``` -**Scope rules:** -- Always use lowercase -- No spaces allowed -- Use hyphens for multi-word scopes (e.g., `pre-commit`) -- Choose the most specific scope for your change -- Scopes avoid redundancy with types (no `docs`, `ci`, `build`, `test` scopes) -- If the scope you need isn't in the list, discuss adding it to `.gitlint` +**DECISION POINT: Number of staged files?** -**Sensible combinations:** -- `feat(auth):` - New authentication feature -- `fix(api):` - Fix API bug -- `docs(readme):` - Update README (not `docs(docs):`) -- `style(python):` - Format Python code -- `chore(deps):` - Update dependencies -- `ci(workflow):` - Modify CI workflow (not `ci(ci):`) -- `test(auth):` - Add auth tests (not `test(test):`) +**IF 0 files:** +→ Display: "No files staged. Use `git add <file>` first." +→ ABORT -## Commit Message Examples +**IF 1-4 files, same scope:** +→ PROCEED to STEP 2 -### Simple Commit +**IF 5+ files OR mixed scopes:** +→ Display: "⚠️ Multiple logical changes detected. Split into separate commits:" +→ List files grouped by suggested commits +→ Ask user: "Commit all together or split?" +→ IF split: guide user through staged commits +→ IF together: PROCEED with caution -```bash -git commit -m "fix(auth): resolve login timeout issue" -``` +### STEP 2: DETERMINE COMMIT DETAILS -### Commit with Body +**Analyze staged files to determine:** +- **Type:** feat/fix/docs/etc. based on changes +- **Scope:** from file paths and affected area +- **Description:** what changed (imperative mood, <50 chars) +- **Body:** why changed (if not obvious) +- **Footer:** issue references (Fixes #N, Related to #N) -```bash -git commit -m "feat(dashboard): add user profile widget +**Present to user:** +```text +Proposed commit: -Add a new profile widget to the dashboard showing user information -and recent activity. The widget is responsive and integrates with -the existing theme system. +Type: feat +Scope: auth +Description: add password validation +Body: Implement password strength validation with minimum requirements... +Footer: Related to #42 -Includes unit tests for the new component and updates to the -dashboard layout." +Proceed? (yes/modify/abort) ``` -### Commit with Breaking Change +### STEP 3: CREATE COMMIT ```bash -git commit -m "feat(api): redesign user endpoints +git commit -m "<type>(<scope>): <description> -BREAKING CHANGE: User API endpoints now require authentication -headers. Update your client code to include Bearer tokens. +<body> -- Removed anonymous access to /api/users -- Added JWT validation middleware -- Updated API documentation" +<footer>" ``` -### Commit Referencing Issues - -```bash -git commit -m "fix(db): handle connection pool exhaustion - -Fix database connection pool exhaustion under high load by -implementing proper connection cleanup and retry logic. +**IF pre-commit hooks fail:** +→ Read hook output +→ Identify failure type: -Closes #123 -Related to #456" +**Auto-fixable (end-of-file, whitespace):** +```text +⚠️ Pre-commit auto-fixed files. Re-running commit... ``` +→ Re-run identical commit command +→ IF fails again: analyze and fix manually -## ⚠️ Critical: Split Large Commits +**Linting errors:** +```bash +# Python +uv run ruff check --fix . +uv run ruff format . -**ALWAYS review staged files before committing.** +# Shell +shellcheck script.sh -If you have **5+ files** or **multiple unrelated changes**, split into separate commits: +# Markdown +# Fix line length, formatting issues +``` +→ Fix issues +→ Re-stage fixed files +→ Retry commit -### Signs You Need Multiple Commits +**Gitlint errors (wrong type/scope):** +→ Fix commit message format +→ Use correct type/scope from allowed lists +→ Retry commit -❌ **Don't commit together:** -- Feature + bug fix -- Code + documentation -- Implementation + tests (sometimes separate is better) -- Multiple unrelated features -- Config changes + code changes -- Different scopes/areas +**NEVER use `--no-verify` without explicit user permission.** -✅ **Group by:** -- Logical units of work -- Single purpose/scope -- Related files only -- Same commit type +**IF need to skip hooks:** +→ Ask user: "Pre-commit hook failed: <reason>. Skip hooks? (yes/no)" +→ Only if user says "yes": +```bash +git commit --no-verify -m "message" +``` -### Example: Splitting a Large Change +### STEP 4: CONFIRM SUCCESS -**Bad (10 files, mixed purposes):** +```text +✅ Commit created -```bash -git add . # ❌ Everything at once -git commit -m "add feature and fix bugs and update docs" +[abc1234] type(scope): description +Files changed: N +Insertions: +X +Deletions: -Y ``` -**Good (split into logical commits):** +## COMMIT SPLITTING RULES +**MUST split if:** +- 5+ files +- Different types (feat + fix = 2 commits) +- Different scopes (auth + api = 2 commits) +- Unrelated changes + +**Split example:** ```bash -# Commit 1: Core feature +# Commit 1: Core implementation git add src/auth.py src/models.py git commit -m "feat(auth): add password validation" @@ -168,325 +180,101 @@ git commit -m "test(auth): add validation tests" # Commit 3: Documentation git add docs/auth.md README.md -git commit -m "docs(auth): document password requirements" +git commit -m "docs(readme): document password requirements" # Commit 4: Config git add config/settings.py git commit -m "chore(config): add auth settings" ``` -## Interactive Commit Workflow - -### 1. Stage Your Changes - -**⚠️ STOP before `git add .`** - -Review what changed first: - -```bash -# See ALL changes -git status - -# Count modified files -git status --short | wc -l -``` - -**Decision tree:** -- **1-4 files, same purpose** → Stage all together -- **5+ files** → Review if they should be split -- **Different types/scopes** → Definitely split - -```bash -# Stage selectively -git add src/auth.py tests/test_auth.py - -# Or stage all (only if related) -git add . - -# Or interactively stage hunks -git add -p -``` - -### 2. Review Changes - -```bash -# See what will be committed -git diff --staged - -# See affected files -git status - -# Count staged files -git diff --staged --name-only | wc -l -``` - -**If you see 5+ files:** -- Ask yourself: "Do these all belong together?" -- If no: Unstage and commit in batches - -### 3. Create Commit - -```bash -# For simple commits -git commit -m "fix(auth): resolve timeout bug" - -# For complex commits (opens editor) -git commit -``` - -### 4. Push (if ready) - -```bash -git push origin your-branch -``` - -## Best Practices - -### Atomic Commits - -**Each commit should be ONE logical change.** - -**Atomic = Single-purpose, focused, reviewable** - -✅ **Good (separate commits):** - -```bash -git commit -m "feat(auth): add password validation" -git commit -m "feat(auth): add password strength meter" -git commit -m "test(auth): add validation tests" -``` - -❌ **Bad (mixed purposes):** - -```bash -git commit -m "add auth features and tests and fix docs" -``` - -### When to Split Commits - -Split if you have: -- ✂️ **5+ files** → Likely multiple logical changes -- ✂️ **Different types** → feat + fix + docs = 3 commits -- ✂️ **Different scopes** → auth + api + ui = 3 commits -- ✂️ **Unrelated changes** → Even if same file - -**Rule of thumb:** If you use "and" in commit message, split it! - -### Commit Frequency - -**Commit early and often:** -- After completing a logical unit of work -- Before switching tasks -- At natural stopping points -- Before risky operations (rebases, merges) - -**Don't commit:** -- Incomplete work: `git commit -m "wip"` -- Multiple unrelated changes -- Formatting only (use `style:` type) -- Debug code (remove before commit) - -### Commit Message Quality +## MESSAGE QUALITY RULES **Subject line:** -- ✅ Imperative mood: "add", "fix", "update" (not "added", "fixed") -- ✅ Lowercase first word after colon: `feat(auth): add login` -- ✅ No period at end -- ✅ Under 50 characters +- Imperative mood: "add" not "added" +- Lowercase after colon: `feat(auth): add login` +- No period at end +- Under 50 characters **Body:** - Explain what and why, not how - Wrap at 72 characters -- Separate from subject with blank line -- Use bullet points for multiple changes - -### Squashing Commits - -**Before PR, consider squashing trivial commits:** - -```bash -# Interactive rebase last 3 commits -git rebase -i HEAD~3 - -# Mark commits to squash with 's' -pick abc1234 feat(auth): add user authentication -s def5678 style(auth): fix typo in auth module -s ghi9012 test(auth): add authentication tests -``` - -## Pre-commit Hooks - -**Hooks run automatically on commit:** -- Gitlint (commit message validation) -- Ruff (Python linting/formatting) -- Shellcheck (shell script linting) -- Pymarkdown (markdown linting) -- Trailing whitespace removal -- End-of-file fixes +- Blank line after subject +- Bullet points for multiple items -**⚠️ NEVER skip hooks without explicit permission:** +## PRE-COMMIT HOOKS -**AI Assistants:** Do NOT use `--no-verify` unless: -1. The user explicitly requests it, OR -2. You ask the user first and get approval +**Hooks run automatically:** +- Gitlint (message validation) +- Ruff (Python lint/format) +- Shellcheck (shell scripts) +- Pymarkdown (markdown) +- Trailing whitespace fix +- End-of-file fix -**When hooks fail:** -1. **STOP** - Do not automatically retry with `--no-verify` -2. **FIX** the issues reported by the hooks -3. **EXPLAIN** what failed and what you're fixing -4. **ASK** the user if they want to skip hooks (only if fixing isn't possible) -5. **COMMIT** only after fixing or getting explicit approval to skip +**Hook failure protocol:** +1. Read error output +2. Fix issues +3. Re-stage files +4. Retry commit +5. ONLY skip if user explicitly approves -**Valid reasons to ask permission to skip:** -- Pre-existing linting errors in files you didn't change -- Build artifacts that don't exist yet but will be generated -- Urgent hotfixes (user must explicitly request) - -**Example when asking:** - -```text -The pre-commit hook failed because: -- pymarkdown found formatting issues in README.md (pre-existing) -- Typst files reference build artifacts that don't exist yet - -Would you like me to: -1. Fix the markdown formatting issues first? (recommended) -2. Skip hooks for this commit? (use --no-verify) -``` - -**Only after user approval:** - -```bash -git commit --no-verify -m "fix(auth): urgent security patch" -``` - -## Common Scenarios - -### Fix Last Commit Message +## COMMON OPERATIONS +**Amend last commit:** ```bash -git commit --amend -m "fix(auth): correct login validation" +git commit --amend -m "fixed message" ``` -### Add Forgotten File to Last Commit - +**Add forgotten file:** ```bash -git add forgotten-file.py +git add forgotten.py git commit --amend --no-edit ``` -### Undo Last Commit (Keep Changes) - +**Undo last commit (keep changes):** ```bash git reset --soft HEAD~1 ``` -### Undo Last Commit (Discard Changes) - +**Revert a commit:** ```bash -git reset --hard HEAD~1 +git revert <commit-hash> ``` -### Revert a Commit +## ERROR RECOVERY -```bash -git revert abc1234 -``` +**"files were modified by this hook":** +→ Normal behavior (auto-fix) +→ Re-run identical commit command +→ Will succeed on second attempt -## Troubleshooting +**"invalid type/scope":** +→ Use type from allowed list +→ Use scope from `.gitlint` +→ Fix message format -### Commit Rejected by Hooks +**"too many files":** +→ Unstage: `git reset` +→ Stage groups: `git add file1 file2` +→ Commit each group separately -```bash -# Fix linting errors -uv run ruff check --fix . +**"wrong branch":** +→ Check: `git branch --show-current` +→ Switch: `git checkout correct-branch` +→ Cherry-pick if needed: `git cherry-pick <hash>` -# Check shell scripts -shellcheck script.sh - -# Commit rejected for missing/invalid scope? -# Use a scope from the allowed list (see Scope Guidelines) - -# Then commit -git add . -git commit -m "fix(linter): resolve linting issues" -``` - -### Wrong Branch - -```bash -# Check current branch -git branch --show-current - -# Switch branch -git checkout correct-branch - -# Cherry-pick if needed -git cherry-pick commit-hash -``` - -### Large Commit (Too Many Files) - -**If you have 5+ staged files, split them:** - -```bash -# See what's staged -git status - -# If too many files, unstage all -git reset - -# Commit in logical groups -git add src/auth/*.py -git commit -m "feat(auth): implement authentication" - -git add tests/test_auth*.py -git commit -m "test(auth): add authentication tests" +## EXECUTION CHECKLIST -git add docs/auth.md -git commit -m "docs(auth): document authentication flow" - -git add config/settings.py -git commit -m "chore(config): add auth configuration" -``` - -**Pro tip:** Use `git add -p` to stage specific hunks within files - -## Quick Reference - -### Commit Types Cheat Sheet - -```text -feat(scope): New feature -fix(scope): Bug fix -docs(scope): Documentation -style(scope): Formatting -refactor(scope): Code restructure -perf(scope): Performance -test(scope): Tests -chore(scope): Maintenance -ci(scope): CI/CD -build(scope): Build system -revert(scope): Revert commit -``` - -**Note:** All commits REQUIRE a scope from the allowed list (see Scope Guidelines above). - -### Fast Commit Commands - -**⚠️ Use with caution - only for 1-4 related files:** - -```bash -# Quick fix -git add . && git commit -m "fix(api): quick bug fix" - -# Feature commit (related files only) -git add src/component.py && git commit -m "feat(ui): add new component" - -# Documentation -git add docs/ && git commit -m "docs(readme): update API guide" -``` +- [ ] Files staged selectively (not `git add .` for 5+ files) +- [ ] Changes reviewed with `git diff --staged` +- [ ] Commit message follows format +- [ ] Type from allowed list +- [ ] Scope from allowed list +- [ ] Description imperative, <50 chars +- [ ] Issue references in footer +- [ ] Pre-commit hooks pass +- [ ] No `--no-verify` unless approved --- -**See [git-workflow.md](./../git-workflow.md) for complete Git workflow and commit guidelines.** +**CRITICAL:** Never commit without reviewing changes. Never skip hooks without permission. Never mix unrelated changes. diff --git a/.cursor/commands/solve-issue.md b/.cursor/commands/solve-issue.md index 1bce44a..e3cdf11 100644 --- a/.cursor/commands/solve-issue.md +++ b/.cursor/commands/solve-issue.md @@ -1,673 +1,585 @@ # Solve Issue Command -This command provides a comprehensive workflow for solving GitHub issues with proper planning, implementation, and pull request submission. +**METHODICAL ISSUE SOLVING - USER FEEDBACK REQUIRED** -**Usage:** `/solve-issue <issue-number>` +Execute `/solve-issue <issue-number>` for careful planning, implementation, and PR creation with user checkpoints. -For complete documentation on related workflows, see: +## EXECUTION PROTOCOL -**Related Documentation:** - -- **[Git Commit Guidelines](./git-commit.md)** -- **[Pull Request Guidelines](./create-pr.md)** -- **[Git Workflow](./../git-workflow.md)** -- **[PR Template](./../pr-template.md)** - -## ⚠️ CRITICAL: Methodical Approach Required - -This command emphasizes **careful planning, user feedback, and clean commits**. For an automated approach, see [yolo-issue.md](./yolo-issue.md). - -## Workflow - -### 1. Fetch and Analyze the Issue - -**Get issue details:** +### STEP 1: FETCH ISSUE ```bash -# Get current repo REPO=$(gh repo view --json nameWithOwner --jq .nameWithOwner) - -# Fetch issue details gh issue view <issue-number> --json number,title,body,labels,state,assignees ``` -**Analyze:** -- Read the issue description carefully -- Identify the problem or feature request -- Note any acceptance criteria -- Check for related issues or dependencies -- Review any labels or assignees +**Display to user:** +```text +📋 Issue #<number>: <title> -**Output to user:** -- Issue title and number -- Description summary -- Current state -- Your initial understanding of the task +<summary of description> -### 2. Check Repository State +State: <state> +Labels: <labels> +Assignees: <assignees> + +Initial understanding: +[Your analysis of what needs to be done] +``` -**⚠️ CRITICAL: Verify clean working directory** +### STEP 2: CHECK REPOSITORY STATE ```bash git status ``` -**If NOT clean (uncommitted changes exist):** - -❌ **STOP IMMEDIATELY** and inform the user: +**DECISION POINT: Working directory clean?** +**IF NOT clean:** ```text -⚠️ Cannot proceed with issue resolution! +⚠️ Cannot proceed - uncommitted changes detected -Your working directory has uncommitted changes: -[list the modified/untracked files] +Modified files: +[list files] -You must commit or stash these changes before starting work on an issue. +Action required: +1. Commit: /git-commit +2. Stash: git stash save "wip" +3. Discard: git restore . (DESTRUCTIVE) -Options: -1. Commit changes: See git-commit.md for guidelines -2. Stash changes: git stash save "description" -3. Discard changes: git restore . (⚠️ destructive) - -After cleaning up, run this command again. +Run /solve-issue again after cleanup. ``` +→ ABORT -**If clean (working tree clean):** - -✅ Proceed to next step +**IF clean:** +→ Display: "✅ Working directory clean" +→ PROCEED to STEP 3 -### 3. Create and Checkout Issue Branch - -**Check if branch exists:** +### STEP 3: CREATE BRANCH ```bash -# Check local branches -git branch --list "issue<issue-number>" - -# Check remote branches -git branch -r --list "origin/issue<issue-number>" +# Check if branch exists +git branch --list "issue<number>" +git branch -r --list "origin/issue<number>" ``` -**Branch naming:** `issue<number>` (e.g., `issue42`) - -**If branch doesn't exist:** +**DECISION POINT: Branch exists?** +**IF NO:** ```bash -# Ensure main is up to date git checkout main git pull origin main - -# Create new branch git checkout -b issue<issue-number> ``` +→ Display: "✅ Created branch: issue<number>" -**If branch already exists locally:** - +**IF YES (locally):** ```bash -# Checkout existing branch git checkout issue<issue-number> - -# Update from remote if it exists -git pull origin issue<issue-number> 2>/dev/null || echo "No remote branch yet" - -# Rebase on latest main +git pull origin issue<issue-number> 2>/dev/null || true git rebase main ``` +→ Display: "✅ Checked out existing branch: issue<number>" +→ If rebase conflicts: guide resolution -**Confirm to user:** -- ✓ Branch: `issue<number>` -- ✓ Based on latest `main` -- ✓ Ready for development - -### 4. Create Implementation Plan +**PROCEED to STEP 4** -**Create `.cursor/plans/` directory if it doesn't exist:** +### STEP 4: CREATE IMPLEMENTATION PLAN ```bash mkdir -p .cursor/plans ``` -**Generate comprehensive plan and save to:** `.cursor/plans/issue-<number>.md` +**Generate plan:** `.cursor/plans/issue-<number>.md` **Plan structure:** - ```markdown # Issue #<number>: <title> ## Problem Statement - -[Clear description of the issue/feature] +[Clear description] ## Analysis ### Current State -- [What exists now] -- [Relevant code locations] -- [Dependencies/constraints] +- Existing code/behavior +- Relevant files +- Dependencies/constraints ### Required Changes -- [What needs to change] -- [Files to modify] -- [New files to create] +- What needs to change +- Files to modify +- New files to create ## Implementation Options -### Option 1: [Approach Name] - -**Description:** [How this approach works] - -**Pros:** -- [Advantage 1] -- [Advantage 2] - -**Cons:** -- [Disadvantage 1] -- [Disadvantage 2] - -**Estimated Complexity:** Low/Medium/High - -**Files to modify:** -- `path/to/file1.py` -- `path/to/file2.py` +### Option 1: [Name] +**Description:** [How it works] +**Pros:** [Advantages] +**Cons:** [Disadvantages] +**Complexity:** Low/Medium/High +**Files:** [List] -### Option 2: [Alternative Approach] +### Option 2: [Alternative] +[Same structure] -[Same structure as Option 1] - -### Option 3: [Another Alternative] - -[Same structure as Option 1] +### Option 3: [Another] +[Same structure] ## Recommended Approach - **Choice:** Option [X] - -**Rationale:** [Why this is the best approach] +**Rationale:** [Why] ## Implementation Steps - -1. [Step 1 with file references] -2. [Step 2 with file references] -3. [Step 3 - Add tests] -4. [Step 4 - Update documentation] -5. [Step 5 - Update CHANGELOG.md] +1. [Step with files] +2. [Step with files] +3. Add tests +4. Update docs +5. Update CHANGELOG ## Testing Strategy - -- [Unit tests to add] -- [Integration tests needed] -- [Manual testing steps] +- Unit tests +- Integration tests +- Manual testing ## Acceptance Criteria - - [ ] [Criterion 1] - [ ] [Criterion 2] -- [ ] [All tests pass] -- [ ] [Documentation updated] -- [ ] [CHANGELOG.md updated] - -## Related Issues/PRs - -- Related to #[X] -- Depends on #[Y] +- [ ] Tests pass +- [ ] Docs updated +- [ ] CHANGELOG updated ``` -**After creating the plan:** - -1. **Display the plan to the user** -2. **If multiple viable options exist, ASK FOR FEEDBACK:** +**Display plan to user.** +**IF multiple viable options:** ```text -I've created an implementation plan with 3 approaches: - -Option 1 (Recommended): [Brief description] - Pros: [Key advantages] - Cons: [Key disadvantages] +Implementation Plan Created -Option 2: [Brief description] - Pros: [Key advantages] - Cons: [Key disadvantages] +I've identified 3 approaches: -Option 3: [Brief description] - Pros: [Key advantages] - Cons: [Key disadvantages] +Option 1 (Recommended): [brief description] + Pros: [key advantages] + Cons: [key disadvantages] -My recommendation is Option 1 because [rationale]. +Option 2: [brief description] + Pros: [key advantages] + Cons: [key disadvantages] -Would you like me to: -1. Proceed with Option 1 (recommended) -2. Use Option 2 -3. Use Option 3 -4. Modify the plan +Option 3: [brief description] + Pros: [key advantages] + Cons: [key disadvantages] -Please confirm or provide feedback. -``` +Recommendation: Option 1 because [rationale] -**Wait for user confirmation before implementing** +Choose: +1) Proceed with Option 1 (recommended) +2) Use Option 2 +3) Use Option 3 +4) Modify plan -### 5. Implement the Solution +Response: +``` -**Follow these principles throughout implementation:** +**WAIT for user response.** -#### Commit Strategy (Critical) +**After user confirms:** +→ PROCEED to STEP 5 -**Make regular, atomic commits** following [git-commit.md](./git-commit.md): +### STEP 5: IMPLEMENT SOLUTION -**Commit frequency guidelines:** -- After each logical unit of work (every 30-60 mins of work) -- When a specific step in the plan is complete -- Before making risky changes -- When tests pass for a component +**Commit strategy: 3-5 atomic commits** -**Commit structure examples:** +**Phase structure:** +**Phase 1: Core Implementation** +→ Implement core functionality +→ Commit: ```bash -# Step 1: Initial implementation -git add src/module.py -git commit -m "feat(module): implement core functionality for issue #42" - -# Step 2: Add tests -git add tests/test_module.py -git commit -m "test(module): add unit tests for issue #42" +git add <files> +git commit -m "feat/fix(scope): implement core functionality for #<n> -# Step 3: Documentation -git add docs/module.md -git commit -m "docs(module): document new functionality for issue #42" +[Detailed description] +[Key decisions] +[Trade-offs] -# Step 4: Update changelog -git add CHANGELOG.md -git commit -m "docs(changelog): add entry for issue #42" +Related to #<n>" ``` -**⚠️ ALWAYS reference issue number in commits:** -- In commit message body: `Fixes #42` or `Related to #42` -- In commit description for context - -#### Code Quality Standards - -**Follow these principles:** -- ✅ **SOLID principles** - Single responsibility, proper abstraction -- ✅ **DRY** - Don't repeat yourself, extract common logic -- ✅ **Clear naming** - Descriptive variable and function names -- ✅ **Proper error handling** - Handle edge cases gracefully -- ✅ **Type hints** - Use type annotations (Python/TypeScript) -- ✅ **Documentation** - Docstrings for functions/classes -- ✅ **No magic numbers** - Use named constants -- ✅ **Configuration over hardcoding** - Use config files/env vars - -#### Testing Requirements - -**Add tests for:** -- ✅ Core functionality (unit tests) -- ✅ Edge cases and error conditions -- ✅ Integration points -- ✅ Regression tests if fixing a bug - -**Test coverage:** -- Aim for high coverage of new/modified code -- Include both positive and negative test cases - -#### Pre-commit Hooks - -**All commits must pass pre-commit hooks** (see [git-commit.md](./git-commit.md)): -- If hooks fail, **FIX the issues** before committing -- **NEVER use `--no-verify`** without asking user first -- Common hook failures: linting errors, formatting issues, trailing whitespace - -#### Progress Updates - -**Keep user informed:** -- Show progress after each major step -- Explain what you're implementing -- Show test results -- Report any blockers or questions +**Phase 2: Tests** (if code changes) +→ Add unit/integration tests +→ Commit: +```bash +git add tests/ +git commit -m "test(scope): add comprehensive tests for #<n> -### 6. Final Verification +Tests include: +- Unit tests for [components] +- Integration tests for [workflows] +- Edge cases: [scenarios] +- Error handling: [conditions] -**Before creating PR, verify:** +Related to #<n>" +``` +**Phase 3: Refactoring** (if needed) +→ Apply SOLID principles +→ Remove duplication +→ Commit: ```bash -# 1. All tests pass -[run test command based on project] +git add <files> +git commit -m "refactor(scope): enhance code quality for #<n> -# 2. Working directory is clean -git status # Should be clean +Applied SOLID principles: +- [Specific refactorings] -# 3. Review all commits -git log --oneline origin/main..HEAD +Removed duplication: +- [Extracted functions] -# 4. Check diff -git diff origin/main...HEAD +Related to #<n>" ``` -**Checklist:** -- [ ] All planned steps completed -- [ ] Tests added and passing -- [ ] Documentation updated -- [ ] CHANGELOG.md updated (if user-facing change) -- [ ] No debug code, console.logs, or TODOs left -- [ ] All commits follow conventional format -- [ ] Pre-commit hooks passed on all commits - -### 7. Create Pull Request +**Phase 4: Documentation** +→ Update README, docs, docstrings +→ Commit: +```bash +git add docs/ README.md +git commit -m "docs(scope): document solution for #<n> -**Push the branch:** +Added: +- Docstrings for functions +- README section on [feature] +- Usage examples -```bash -git push origin issue<issue-number> +Related to #<n>" ``` -**Create PR using GitHub CLI:** - +**Phase 5: CHANGELOG** +→ Update CHANGELOG.md +→ Commit: ```bash -gh pr create \ - --title "fix/feat: <description> (closes #<issue-number>)" \ - --body "## Description - -[Description of changes] +git add CHANGELOG.md +git commit -m "docs(changelog): add entry for #<n> -## Changes +[User-facing change description] -- [Change 1] -- [Change 2] +Fixes #<n>" +``` -## Testing +**During implementation:** +- Keep user informed of progress +- Show test results +- Report blockers/questions +- Ask for feedback on trade-offs + +**Code quality standards:** +- SOLID principles +- DRY (no duplication) +- Clear naming +- Type hints/annotations +- Proper error handling +- No magic numbers/hardcoding +- Configuration over hardcoding + +**IF pre-commit hooks fail:** +→ Read error output +→ Fix issues automatically +→ Re-stage files +→ Retry commit +→ NEVER use `--no-verify` without asking + +**IF blockers encountered:** +```text +⚠️ Blocker Encountered -- [x] Unit tests added -- [x] All tests passing -- [x] Manual testing completed +Issue: [Description] -## Related Issues +Impact: [What's blocked] -Closes #<issue-number> +Options: +1. [Option A - pros/cons] +2. [Option B - pros/cons] -## Implementation Plan +Recommendation: [Your suggestion] -See: .cursor/plans/issue-<number>.md" \ - --draft +How should we proceed? ``` +→ WAIT for user response -**PR title format:** -- Use conventional commit type: `fix:`, `feat:`, `docs:`, etc. -- Include brief description -- Reference issue: `(closes #42)` or `(fixes #42)` - -**Example titles:** -- `feat: add user authentication (closes #42)` -- `fix: resolve database connection timeout (fixes #123)` -- `docs: update API documentation (closes #67)` +### STEP 6: FINAL VERIFICATION -**After PR creation:** - -1. **Inform user:** - - ✓ PR created (show URL) - - ✓ Status: Draft - - ✓ Linked to issue #X - - ✓ Implementation plan included - -2. **Next steps:** - - Wait for CI checks - - Address any automated feedback - - Mark as "Ready for review" when ready - - Respond to review comments +```bash +# Run tests +[project-specific test command] -### 8. Mark PR Ready for Review +# Check status +git status -**After CI passes and you're confident:** +# Review commits +git log --oneline origin/main..HEAD -```bash -gh pr ready <pr-number> +# Check diff +git diff origin/main...HEAD ``` -**Inform user:** +**Verification checklist:** +- [ ] All planned steps completed +- [ ] Tests added and passing +- [ ] Documentation updated +- [ ] CHANGELOG.md updated +- [ ] No debug code/TODOs +- [ ] All commits follow format +- [ ] Pre-commit hooks passed +- [ ] Working directory clean +**Display results to user:** ```text -✅ Issue #<number> solution complete! +✅ Implementation Complete Summary: -- Branch: issue<number> -- Commits: <count> atomic commits -- Tests: All passing -- PR: #<pr-number> (ready for review) -- Plan: .cursor/plans/issue-<number>.md +- Steps completed: [list] +- Tests added: [count] +- Files modified: [count] +- Commits: [count] -The PR is now ready for maintainer review. +Ready to create PR ``` -## Best Practices - -### Planning Phase - -- **Thorough analysis** - Understand the issue completely before coding -- **Multiple options** - Consider different approaches -- **Get feedback** - Ask user for preference when there are trade-offs -- **Document plan** - Save plan for future reference - -### Implementation Phase +**Ask user:** "Proceed with PR creation? (yes/review/modify)" -- **Atomic commits** - Small, focused commits (review [git-commit.md](./git-commit.md)) -- **Test as you go** - Don't leave testing until the end -- **Follow style** - Match existing code style and patterns -- **Incremental progress** - Complete one step before moving to next +**WAIT for confirmation.** -### Quality Checklist - -Before committing any code: -- [ ] Follows project coding standards -- [ ] No hardcoded values (use constants/config) -- [ ] Proper error handling -- [ ] Type hints/annotations added -- [ ] Docstrings for new functions/classes -- [ ] No commented-out code -- [ ] No console.logs or debug prints -- [ ] Imports organized properly - -### Communication - -- **Be transparent** - Share your reasoning -- **Ask when uncertain** - Don't guess on ambiguous requirements -- **Explain trade-offs** - When there are multiple valid approaches -- **Show progress** - Keep user updated on long-running tasks - -## Common Scenarios - -### Scenario 1: Simple Bug Fix +### STEP 7: PUSH BRANCH ```bash -# 1. Fetch issue -gh issue view 42 - -# 2. Check clean -git status - -# 3. Create branch -git checkout -b issue42 - -# 4. Create simple plan -# (Can be brief for obvious bugs) - -# 5. Fix + test + commit -git commit -m "fix(api): resolve timeout in /users endpoint - -Increased connection timeout from 5s to 30s to handle -slow database queries during peak hours. - -Fixes #42" - -# 6. Update changelog -git commit -m "docs(changelog): add fix for issue #42" - -# 7. PR -gh pr create --title "fix: resolve API timeout (fixes #42)" +git push -u origin issue<issue-number> ``` -### Scenario 2: Complex Feature - +**IF auth failure:** ```bash -# 1. Fetch issue -gh issue view 67 - -# 2. Extensive analysis -# - Review related code -# - Identify dependencies -# - Consider architecture - -# 3. Create detailed plan with options -# - Save to .cursor/plans/issue-67.md -# - Present options to user -# - Wait for feedback - -# 4. Implement in phases -# Phase 1: Core logic (commit) -# Phase 2: Tests (commit) -# Phase 3: Integration (commit) -# Phase 4: Documentation (commit) -# Phase 5: Changelog (commit) - -# 5. Create PR with comprehensive description +gh auth setup-git +git push -u origin issue<issue-number> ``` -### Scenario 3: Issue Requires Clarification - -```text -After analyzing issue #89, I have questions: +### STEP 8: CREATE PR -The issue states "improve performance" but doesn't specify: -1. Which operation is slow? -2. What's the current performance baseline? -3. What's the target performance? - -I recommend: -- Commenting on the issue to ask for clarification -- OR making reasonable assumptions and documenting them - -How would you like to proceed? +**Generate PR title:** +``` +<type>: <description> (closes #<issue-number>) ``` -## Troubleshooting - -### Working Directory Not Clean +**Generate PR body:** +```markdown +## Description +[Summary of changes] -```text -⚠️ Cannot start: uncommitted changes detected +## Implementation +[Approach taken and rationale] -Modified files: - M src/app.py - M tests/test_app.py +See plan: `.cursor/plans/issue-<number>.md` -Please commit these first: - git add src/app.py tests/test_app.py - git commit -m "feat(app): describe your changes" +## Changes -Or stash them: - git stash save "work in progress" +### Core Implementation +- <file>: <what changed> -Then run solve-issue again. -``` +### Tests +- <test-file>: <coverage> -### Branch Already Exists +### Documentation +- <doc-file>: <updates> +- CHANGELOG.md: Entry added -```bash -# If local branch exists -git checkout issue42 -git rebase main # Update with latest +## Testing +- [x] Unit tests added +- [x] Integration tests added +- [x] All tests passing +- [x] Manual testing completed +- [x] Edge cases covered -# If you want to start fresh -git branch -D issue42 -git checkout -b issue42 -``` +## Quality Checks +- [x] Pre-commit hooks passed +- [x] No linting errors +- [x] Documentation complete +- [x] CHANGELOG updated +- [x] Follows project conventions +- [x] No debug code -### Pre-commit Hooks Failing +## Related Issues +Closes #<issue-number> -**DO NOT skip hooks!** +## Commits +[List commits with brief descriptions] +``` +**Create PR:** ```bash -# Fix the reported issues -# For Python linting -uv run ruff check --fix . +cat > /tmp/pr-body.md << 'EOF' +[PR body] +EOF -# For shell scripts -shellcheck script.sh +gh pr create \ + --title "<type>: <description> (closes #<issue-number>)" \ + --body-file /tmp/pr-body.md \ + --draft -# Then commit -git commit -m "your message" +rm /tmp/pr-body.md ``` -See [git-commit.md](./git-commit.md) for detailed pre-commit hook guidelines. - -### Issue is Complex or Blocked - -**Communicate with user:** +### STEP 9: COMPLETION REPORT ```text -After analyzing issue #X, I've identified some concerns: +✅ Issue #<number> Solution Complete -Blockers: -- Depends on unmerged PR #Y -- Requires database schema changes -- Needs security review +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -Recommendations: -1. Wait for PR #Y to merge -2. Create separate issue for schema migration -3. Implement feature flag for gradual rollout - -Should we proceed with a partial implementation or wait? -``` +Summary: +- Branch: issue<number> +- Commits: <count> atomic commits +- Files changed: <count> +- Tests added: <count> +- PR: #<pr-number> (draft) -## Quick Reference +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -### Command Sequence +Implementation: +[Brief summary of approach] -```bash -# 1. Fetch issue -gh issue view <number> +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -# 2. Verify clean state -git status +Next Steps: +1. Review PR: <url> +2. Mark ready when confident +3. Respond to review feedback +4. Merge when approved -# 3. Create branch -git checkout main && git pull -git checkout -b issue<number> +Plan: .cursor/plans/issue-<number>.md +``` -# 4. Create plan -mkdir -p .cursor/plans -# [Create plan file] +## COMMIT FREQUENCY + +**Make commits:** +- After each logical unit (30-60 min work) +- When step in plan complete +- Before risky changes +- When tests pass for component + +**Reference issue:** +- Body: `Related to #<n>` or `Fixes #<n>` +- Last commit: `Fixes #<n>` in footer + +## COMMUNICATION PRINCIPLES + +**Be transparent:** +- Share reasoning +- Explain trade-offs +- Show progress updates +- Ask when uncertain + +**Ask for feedback:** +- Multiple valid approaches +- Ambiguous requirements +- Performance vs complexity +- Breaking changes + +**Report blockers:** +- Dependencies on other work +- Unclear requirements +- Security/architecture concerns +- Need for user decision + +## SCENARIOS + +**Simple bug fix:** +- Quick analysis +- Brief plan (can skip options) +- 1-2 commits (fix + changelog) +- Quick PR + +**Complex feature:** +- Extensive analysis +- Detailed plan with options +- User feedback required +- 5+ commits +- Comprehensive PR + +**Issue requires clarification:** +```text +After analyzing issue #X, questions: -# 5. Implement with regular commits -git commit -m "type(scope): description +1. [Question about requirement] +2. [Question about scope] +3. [Question about constraints] -Related to #<number>" +Recommend: +- Comment on issue for clarification +- OR make reasonable assumptions (documented) -# 6. Push and PR -git push origin issue<number> -gh pr create --title "type: description (closes #<number>)" --draft +How to proceed? ``` +→ WAIT for user response -### Files to Update +## ERROR RECOVERY -Common files that may need updating: -- **Source code** - Your implementation -- **Tests** - Unit/integration tests -- **Documentation** - README, docs/, docstrings -- **CHANGELOG.md** - User-facing changes -- **Configuration** - If adding new features +**Working directory not clean:** +→ List uncommitted files +→ Guide: commit, stash, or discard +→ ABORT until clean -### Commit Message Template +**Branch exists with conflicts:** +→ Guide rebase +→ Help resolve conflicts +→ Verify clean after resolution -```bash -git commit -m "type(scope): brief description +**Pre-commit hooks fail:** +→ Read error output +→ Fix issues (ruff, shellcheck, etc.) +→ Re-stage files +→ Retry commit +→ NEVER skip without permission -Detailed explanation of what changed and why. -Include context that would help reviewers understand -the changes. +**Issue complex/blocked:** +→ Explain blockers +→ Present options +→ Provide recommendation +→ WAIT for user decision -Related to #<issue-number> -Fixes #<issue-number> # Use this in final commit" -``` +## QUALITY CHECKLIST (EVERY COMMIT) ---- +Before committing: +- [ ] Follows project coding standards +- [ ] No hardcoded values +- [ ] Proper error handling +- [ ] Type hints/annotations +- [ ] Docstrings added +- [ ] No commented code +- [ ] No console.logs/debug prints +- [ ] Imports organized + +## EXECUTION CHECKLIST + +**Pre-execution:** +- [ ] Issue fetched and analyzed +- [ ] Working directory clean +- [ ] Branch created/checked out + +**During execution:** +- [ ] Plan created and approved +- [ ] Implementation follows plan +- [ ] Regular atomic commits +- [ ] Tests added +- [ ] Docs updated +- [ ] CHANGELOG updated +- [ ] User informed of progress + +**Post-execution:** +- [ ] All tests passing +- [ ] Pre-commit hooks passed +- [ ] Final verification complete +- [ ] Branch pushed +- [ ] PR created +- [ ] Plan documented -**For an automated approach without user confirmations, see [yolo-issue.md](./yolo-issue.md).** +--- -**For detailed commit and PR guidelines, see [git-commit.md](./git-commit.md) and [create-pr.md](./create-pr.md).** +**For autonomous approach without user confirmations, see yolo-issue.md** diff --git a/.cursor/commands/tag-and-release.md b/.cursor/commands/tag-and-release.md index 438e2a9..ce7285b 100644 --- a/.cursor/commands/tag-and-release.md +++ b/.cursor/commands/tag-and-release.md @@ -1,428 +1,387 @@ # Tag and Release Command -This command automates the complete git tag creation and GitHub release workflow. +**CREATES GIT TAG AND GITHUB RELEASE - FULLY AUTOMATED** -## Usage +Execute `/tag-and-release` after PR merge to create git tag and GitHub release from CHANGELOG. -```bash -/tag-and-release -``` +## PREREQUISITES -**Purpose:** Create a git tag and GitHub release for the current version in pyproject.toml. +- On `main` branch +- Clean working directory +- Version already bumped in `pyproject.toml` (from `/create-pr`) +- CHANGELOG.md updated with version entry +- All changes committed and merged -## Prerequisites +## EXECUTION PROTOCOL -Before running this command, ensure: +### STEP 1: VALIDATE PREREQUISITES -- [ ] On **main** branch -- [ ] **Clean working directory** (no uncommitted changes) -- [ ] **Version already bumped** in pyproject.toml (done during `/create-pr`) -- [ ] **CHANGELOG.md already updated** with release notes (done during `/create-pr`) -- [ ] All changes **committed and merged** to main - -**Note:** Version bumping and CHANGELOG updates are handled by `/create-pr`. -After PR merge, `/tag-and-release` validates everything and creates the git tag and GitHub release. +```bash +BRANCH=$(git branch --show-current) +``` -## Workflow +**DECISION POINT: On main branch?** -The command performs these steps automatically: +**IF NOT main:** +```text +❌ Error: Must be on main branch +Current: $BRANCH -### 1. Validate Prerequisites +Run: git checkout main +``` +→ ABORT -**Branch Check:** +**IF main:** +→ PROCEED to working directory check ```bash -# Must be on main -BRANCH=$(git branch --show-current) -if [ "$BRANCH" != "main" ]; then - echo "❌ Error: Must be on main branch (currently on: $BRANCH)" - exit 1 -fi +git diff-index --quiet HEAD -- ``` -**Working Directory Check:** +**DECISION POINT: Working directory clean?** -```bash -# Must be clean -if ! git diff-index --quiet HEAD --; then - echo "❌ Error: Working directory has uncommitted changes" - echo "Commit or stash changes before creating release" - exit 1 -fi +**IF NOT clean:** +```text +❌ Error: Uncommitted changes detected + +Modified files: +[list files] + +Action: Commit or stash changes ``` +→ ABORT -### 2. Get and Validate Version +**IF clean:** +→ PROCEED to STEP 2 -**Extract version from pyproject.toml:** +### STEP 2: GET AND VALIDATE VERSION ```bash -# Use make version to get current version VERSION=$(make version | grep -oP '\d+\.\d+\.\d+') -echo "Current version: $VERSION" ``` -**Validate version format:** - +**Validate format (X.Y.Z):** ```bash -# Must match X.Y.Z format (Semantic Versioning) if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then - echo "❌ Error: Invalid version format: $VERSION" - echo "Expected: X.Y.Z (e.g., 0.3.3)" + echo "❌ Invalid version format: $VERSION" exit 1 fi ``` -**Check version is consecutive to existing tags:** - +**Get latest tag:** ```bash -# Get latest tag LATEST_TAG=$(git tag -l | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1) +``` -if [ -z "$LATEST_TAG" ]; then - echo "ℹ️ No previous tags found - this will be the first release" -else - echo "Latest tag: $LATEST_TAG" - echo "New version: $VERSION" - - # Version must be greater than latest tag - LATEST_SEMVER=$(echo "$LATEST_TAG" | sed 's/v//') - if [ "$VERSION" == "$LATEST_SEMVER" ]; then - echo "❌ Error: Version $VERSION already exists as a tag" - echo "Bump version using: make bump-patch/minor/major" - exit 1 - fi - - # Check if version is consecutive (no gaps) - # Parse versions - IFS='.' read -r -a LATEST_PARTS <<< "$LATEST_SEMVER" - IFS='.' read -r -a NEW_PARTS <<< "$VERSION" - - LATEST_MAJOR=${LATEST_PARTS[0]} - LATEST_MINOR=${LATEST_PARTS[1]} - LATEST_PATCH=${LATEST_PARTS[2]} - - NEW_MAJOR=${NEW_PARTS[0]} - NEW_MINOR=${NEW_PARTS[1]} - NEW_PATCH=${NEW_PARTS[2]} - - # Validate consecutive bump - VALID=false - # Major bump: X.0.0 - if [ "$NEW_MAJOR" -eq $((LATEST_MAJOR + 1)) ] && \ - [ "$NEW_MINOR" -eq 0 ] && [ "$NEW_PATCH" -eq 0 ]; then - VALID=true - # Minor bump: 0.X.0 - elif [ "$NEW_MAJOR" -eq "$LATEST_MAJOR" ] && \ - [ "$NEW_MINOR" -eq $((LATEST_MINOR + 1)) ] && \ - [ "$NEW_PATCH" -eq 0 ]; then - VALID=true - # Patch bump: 0.0.X - elif [ "$NEW_MAJOR" -eq "$LATEST_MAJOR" ] && \ - [ "$NEW_MINOR" -eq "$LATEST_MINOR" ] && \ - [ "$NEW_PATCH" -eq $((LATEST_PATCH + 1)) ]; then - VALID=true - fi - - if [ "$VALID" = "false" ]; then - echo "❌ Error: Version $VERSION is not consecutive to $LATEST_SEMVER" - echo "" - echo "Valid next versions:" - echo " - Patch: $LATEST_MAJOR.$LATEST_MINOR.$((LATEST_PATCH + 1))" - echo " - Minor: $LATEST_MAJOR.$((LATEST_MINOR + 1)).0" - echo " - Major: $((LATEST_MAJOR + 1)).0.0" - exit 1 - fi +**DECISION POINT: Latest tag exists?** + +**IF NO tags:** +→ Display: "ℹ️ No previous tags - first release" +→ PROCEED to STEP 3 + +**IF tags exist:** +→ Validate version is consecutive + +**Parse versions:** +```bash +IFS='.' read -r -a LATEST_PARTS <<< "$LATEST_TAG" +IFS='.' read -r -a NEW_PARTS <<< "$VERSION" + +LATEST_MAJOR=${LATEST_PARTS[0]} +LATEST_MINOR=${LATEST_PARTS[1]} +LATEST_PATCH=${LATEST_PARTS[2]} + +NEW_MAJOR=${NEW_PARTS[0]} +NEW_MINOR=${NEW_PARTS[1]} +NEW_PATCH=${NEW_PARTS[2]} +``` + +**Validate consecutive:** +```bash +VALID=false + +# Major bump: X.0.0 +if [ "$NEW_MAJOR" -eq $((LATEST_MAJOR + 1)) ] && \ + [ "$NEW_MINOR" -eq 0 ] && [ "$NEW_PATCH" -eq 0 ]; then + VALID=true +# Minor bump: 0.X.0 +elif [ "$NEW_MAJOR" -eq "$LATEST_MAJOR" ] && \ + [ "$NEW_MINOR" -eq $((LATEST_MINOR + 1)) ] && \ + [ "$NEW_PATCH" -eq 0 ]; then + VALID=true +# Patch bump: 0.0.X +elif [ "$NEW_MAJOR" -eq "$LATEST_MAJOR" ] && \ + [ "$NEW_MINOR" -eq "$LATEST_MINOR" ] && \ + [ "$NEW_PATCH" -eq $((LATEST_PATCH + 1)) ]; then + VALID=true fi ``` -### 3. Validate CHANGELOG.md Format +**IF NOT consecutive:** +```text +❌ Error: Version $VERSION not consecutive to $LATEST_TAG + +Valid next versions: +- Patch: $LATEST_MAJOR.$LATEST_MINOR.$((LATEST_PATCH + 1)) +- Minor: $LATEST_MAJOR.$((LATEST_MINOR + 1)).0 +- Major: $((LATEST_MAJOR + 1)).0.0 + +Current: $LATEST_TAG +Attempted: $VERSION +``` +→ ABORT + +**IF consecutive:** +→ PROCEED to STEP 3 -**Check version entry exists:** +### STEP 3: VALIDATE CHANGELOG ```bash -# CHANGELOG must have entry for current version -if ! grep -q "^## \[$VERSION\]" CHANGELOG.md; then - echo "❌ Error: CHANGELOG.md missing entry for version $VERSION" - echo "" - echo "Expected format:" - echo "## [$VERSION] - YYYY-MM-DD" - echo "" - echo "Update CHANGELOG.md before creating release" - exit 1 -fi +grep -q "^## \[$VERSION\]" CHANGELOG.md +``` + +**DECISION POINT: Version entry exists?** + +**IF NOT exists:** +```text +❌ Error: CHANGELOG.md missing entry for $VERSION + +Expected format: +## [$VERSION] - YYYY-MM-DD + +### Added +- Features + +### Changed +- Modifications + +### Fixed +- Bug fixes ``` +→ ABORT -**Validate Keep a Changelog format:** +**IF exists:** +→ Validate format ```bash -# Extract the version entry ENTRY=$(sed -n "/^## \[$VERSION\]/,/^## \[/p" CHANGELOG.md | head -n -1) - -# Check for date DATE_PATTERN="^## \[$VERSION\] - [0-9]\{4\}-[0-9]\{2\}-[0-9]\{2\}" + if ! echo "$ENTRY" | grep -q "$DATE_PATTERN"; then - echo "❌ Error: Version entry missing or incorrectly formatted date" - echo "Expected: ## [$VERSION] - YYYY-MM-DD" + echo "❌ Error: Version entry missing date" exit 1 fi -# Check for at least one category (Added, Changed, Fixed, etc.) CATEGORIES="Added|Changed|Deprecated|Removed|Fixed|Security" if ! echo "$ENTRY" | grep -qE "^### ($CATEGORIES)"; then - echo "❌ Error: CHANGELOG entry must have at least one category" - echo "Categories: Added, Changed, Deprecated, Removed, Fixed, Security" + echo "❌ Error: CHANGELOG must have at least one category" exit 1 fi - -echo "✅ CHANGELOG.md format valid" ``` -### 4. Extract Release Notes +**IF validation fails:** +→ Display specific error +→ ABORT + +**IF validation succeeds:** +→ Display: "✅ CHANGELOG.md format valid" +→ PROCEED to STEP 4 -**Parse CHANGELOG for current version:** +### STEP 4: EXTRACT RELEASE NOTES ```bash -# Extract release notes for this version RELEASE_NOTES=$(sed -n "/^## \[$VERSION\]/,/^## \[/p" CHANGELOG.md | head -n -1) -# Extract title from first line after version header -# Look for main feature/category -RELEASE_TITLE="Release $VERSION" - -# Try to determine feature name from CHANGELOG -# Look for the first major feature in Added or Changed sections +# Determine release title from first major feature FEATURE_NAME=$(echo "$RELEASE_NOTES" | grep -A1 "^### Added" | \ tail -1 | sed 's/^- \*\*//' | sed 's/\*\*.*//' | head -c 40) + if [ -n "$FEATURE_NAME" ]; then RELEASE_TITLE="Release $VERSION - $FEATURE_NAME" +else + RELEASE_TITLE="Release $VERSION" fi ``` -### 5. Create Git Tag - -**Create annotated tag:** +### STEP 5: CREATE GIT TAG ```bash -# Create tag with message from CHANGELOG TAG_MESSAGE="Release $VERSION $RELEASE_NOTES" git tag -a "$VERSION" -m "$TAG_MESSAGE" -echo "✅ Created tag: $VERSION" ``` -### 6. Push Tag +**Display:** "✅ Created tag: $VERSION" -**Push to remote:** +### STEP 6: PUSH TAG ```bash git push --tags -echo "✅ Pushed tag: $VERSION" ``` -### 7. Create GitHub Release +**IF push fails (authentication):** +```bash +gh auth setup-git +git push --tags +``` + +**IF push fails (tag exists remotely):** +```text +❌ Error: Tag $VERSION already exists on remote -**Format release notes:** +To delete and recreate (DANGEROUS): +git push origin :refs/tags/$VERSION +git tag -d $VERSION +[Then run /tag-and-release again] +``` +→ ABORT + +**IF push succeeds:** +→ Display: "✅ Pushed tag: $VERSION" +→ PROCEED to STEP 7 + +### STEP 7: CREATE GITHUB RELEASE ```bash -# Create release with formatted notes -# Add comparison link +# Get previous tag for comparison link PREV_TAG=$(git tag -l | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | \ sort -V | tail -2 | head -1) -COMPARISON_LINK="" + +# Build comparison link if [ -n "$PREV_TAG" ]; then REPO=$(gh repo view --json nameWithOwner --jq .nameWithOwner) COMPARISON_URL="https://github.com/$REPO/compare/$PREV_TAG...$VERSION" COMPARISON_LINK="\n\n---\n\n**Full Changelog**: $COMPARISON_URL" +else + COMPARISON_LINK="" fi # Create release gh release create "$VERSION" \ --title "$RELEASE_TITLE" \ --notes "$RELEASE_NOTES$COMPARISON_LINK" - -echo "✅ Created GitHub release: $VERSION" ``` -## Complete Example - -Here's what the command does step-by-step: - -```bash -# 1. Validate prerequisites -echo "Validating prerequisites..." -# - Check on main branch -# - Check clean working directory - -# 2. Get version -echo "Getting version from pyproject.toml..." -VERSION=$(make version | grep -oP '\d+\.\d+\.\d+') -echo "Current version: $VERSION" - -# 3. Validate version continuity -echo "Validating version continuity..." -LATEST_TAG=$(git tag -l | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1) -echo "Latest tag: $LATEST_TAG" -# - Check version is consecutive (no gaps) +**IF release creation fails:** +→ Check if release already exists: `gh release list | grep $VERSION` +→ If exists: Delete with `gh release delete $VERSION --yes` +→ Retry release creation -# 4. Validate CHANGELOG -echo "Validating CHANGELOG.md..." -# - Check entry exists for $VERSION -# - Validate format: ## [X.Y.Z] - YYYY-MM-DD -# - Check has categories (Added/Changed/Fixed/etc.) +**IF release succeeds:** +→ Display: "✅ Created GitHub release: $VERSION" +→ PROCEED to STEP 8 -# 5. Extract release notes -echo "Extracting release notes from CHANGELOG..." -RELEASE_NOTES=$(sed -n "/^## \[$VERSION\]/,/^## \[/p" CHANGELOG.md | head -n -1) +### STEP 8: COMPLETION REPORT -# 6. Create tag -echo "Creating git tag..." -git tag -a "$VERSION" -m "Release $VERSION +```text +✅ Tag and Release Complete -$RELEASE_NOTES" +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -# 7. Push tag -echo "Pushing tag to remote..." -git push --tags +📦 Release Details -# 8. Create GitHub release -echo "Creating GitHub release..." -gh release create "$VERSION" \ - --title "Release $VERSION - Feature Name" \ - --notes "$RELEASE_NOTES +Version: $VERSION +Previous: $PREV_TAG +Type: [patch/minor/major] ---- +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -**Full Changelog**: https://github.com/ORG/REPO/compare/$PREV_TAG...$VERSION" +✅ Actions Completed -echo "✅ Release complete: $VERSION" -``` +- Git tag created: $VERSION +- Tag pushed to remote +- GitHub release created +- Release notes from CHANGELOG -## Error Handling +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -### Not on Main Branch +🔗 URLs -```text -❌ Error: Must be on main branch (currently on: feature/xyz) +Tag: https://github.com/$REPO/releases/tag/$VERSION +Changelog: https://github.com/$REPO/compare/$PREV_TAG...$VERSION -Switch to main: - git checkout main +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` -### Uncommitted Changes +## ERROR RECOVERY -```text -❌ Error: Working directory has uncommitted changes - -Uncommitted files: - - file1.py - - file2.md - -Action required: - 1. Commit changes: git add . && git commit -m "..." - 2. Or stash: git stash save "wip" +**Tag already exists locally:** +```bash +# Delete local tag +git tag -d $VERSION -Then run /tag-and-release again +# Re-run /tag-and-release ``` -### Version Already Tagged - -```text -❌ Error: Version 0.3.3 already exists as a tag +**Tag exists remotely:** +```bash +# Delete remote tag (CAREFUL - check with team first) +git push origin :refs/tags/$VERSION -Current version in pyproject.toml: 0.3.3 -Existing tags: 0.3.0, 0.3.1, 0.3.2, 0.3.3 +# Delete local tag +git tag -d $VERSION -Action required: - Bump version using: - make bump-patch # → 0.3.4 - make bump-minor # → 0.4.0 - make bump-major # → 1.0.0 +# Re-run /tag-and-release ``` -### Non-Consecutive Version - -```text -❌ Error: Version 0.3.5 is not consecutive to 0.3.2 - -Latest tag: 0.3.2 -New version: 0.3.5 (skips 0.3.3 and 0.3.4) +**Release creation fails (422 Validation):** +```bash +# List releases +gh release list | grep $VERSION -Valid next versions: - - Patch: 0.3.3 - - Minor: 0.4.0 - - Major: 1.0.0 +# If exists, delete +gh release delete $VERSION --yes -Action required: - Update pyproject.toml to a consecutive version +# Re-run /tag-and-release ``` -### Missing CHANGELOG Entry - -```text -❌ Error: CHANGELOG.md missing entry for version 0.3.3 - -Expected format: -## [0.3.3] - 2025-11-10 - -### Added -- New features - -### Changed -- Changes to functionality - -### Fixed -- Bug fixes - -Action required: - 1. Add CHANGELOG entry for version 0.3.3 - 2. Follow Keep a Changelog format - 3. Run /tag-and-release again +**CHANGELOG format invalid:** +→ Edit CHANGELOG.md to match format: +```markdown +## [X.Y.Z] - YYYY-MM-DD -Reference: https://keepachangelog.com/en/1.0.0/ +### Added/Changed/Fixed +- Description ``` +→ Commit changes +→ Re-run `/tag-and-release` -### Invalid CHANGELOG Format +**Version not consecutive:** +→ Bump version correctly: `make bump-patch/minor/major` +→ Update CHANGELOG.md +→ Commit changes +→ Re-run `/tag-and-release` -```text -❌ Error: CHANGELOG entry for 0.3.3 is incorrectly formatted +## VALIDATION CHECKLIST -Found: -## [0.3.3] +**Automatically checked:** +- [ ] On main branch +- [ ] Working directory clean +- [ ] Version format valid (X.Y.Z) +- [ ] Version consecutive to latest tag +- [ ] CHANGELOG entry exists +- [ ] CHANGELOG has date +- [ ] CHANGELOG has categories +- [ ] Git tag created +- [ ] Tag pushed to remote +- [ ] GitHub release created -Expected: -## [0.3.3] - YYYY-MM-DD - -### Added -- Feature 1 - -### Changed -- Change 1 - -Action required: - 1. Add date to version header - 2. Add at least one category section - 3. Add entries under categories - -Reference: https://keepachangelog.com/en/1.0.0/ -``` - -## Keep a Changelog Format Summary - -CHANGELOG.md must follow this structure: +## KEEP A CHANGELOG FORMAT +**Required structure:** ```markdown ## [X.Y.Z] - YYYY-MM-DD ### Added -- New features for users +- New features ### Changed -- Changes to existing functionality +- Modifications ### Deprecated -- Soon-to-be removed features +- Soon-to-be removed ### Removed - Removed features @@ -431,273 +390,37 @@ CHANGELOG.md must follow this structure: - Bug fixes ### Security -- Security vulnerability fixes +- Security fixes ``` -**Requirements:** -- Version header: `## [X.Y.Z] - YYYY-MM-DD` -- Most recent version at top -- At least one category section -- Entries are bullet points -- Focus on user-facing changes - -**Reference:** [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) +**Must have:** +- Version header with date +- At least one category +- Bullet points under categories -## Semantic Versioning Summary +## SEMANTIC VERSIONING -Versions follow **MAJOR.MINOR.PATCH** format (e.g., 1.4.2): +**MAJOR.MINOR.PATCH** -- **MAJOR (X.0.0)**: Incompatible API changes (breaking changes) -- **MINOR (0.X.0)**: New features (backward compatible) -- **PATCH (0.0.X)**: Bug fixes (backward compatible) +**MAJOR (X.0.0):** Breaking changes +**MINOR (0.X.0):** New features (compatible) +**PATCH (0.0.X):** Bug fixes (compatible) **Rules:** -- Never reuse version numbers -- Must be consecutive (no skipping versions) -- Initial development starts at 0.1.0 -- Public API starts at 1.0.0 - -**Reference:** [Semantic Versioning](https://semver.org/spec/v2.0.0.html) - -## Complete Release Workflow - -### Typical Release Process - -```bash -# 1. Work on feature branch -git checkout -b feature/new-feature -# ... make changes ... -git commit -m "feat(scope): add new feature" - -# 2. Create PR with version bump (see create-pr.md) -/create-pr # Will suggest version bump - -# 3. PR gets reviewed and merged to main -# ... review, approve, merge ... - -# 4. Switch to main and pull -git checkout main -git pull origin main - -# 5. Create tag and release -/tag-and-release - -# Done! Tag and release created automatically -``` - -### Quick Release (Already on Main) - -If you're already on main with version bumped and CHANGELOG updated: - -```bash -# Just run the command -/tag-and-release -``` - -It will: -- ✅ Validate everything -- ✅ Create git tag -- ✅ Push tag to remote -- ✅ Create GitHub release with CHANGELOG notes - -## Integration with Version Management - -This command integrates with the version management system: - -```bash -# 1. Bump version -make bump-patch # or bump-minor, bump-major - -# 2. Update CHANGELOG.md -vim CHANGELOG.md -# Add actual changes for the version - -# 3. Commit version bump -git add pyproject.toml CHANGELOG.md -git commit -m "chore(release): bump version to X.Y.Z" - -# 4. Push to main -git push origin main - -# 5. Create tag and release -/tag-and-release -``` - -## Success Output - -```text -🚀 Creating Tag and Release for v0.3.3 - -✅ Prerequisites validated - - On main branch - - Working directory clean - -✅ Version validated: 0.3.3 - - Latest tag: 0.3.2 - - Consecutive bump: ✓ (patch) - -✅ CHANGELOG.md validated - - Entry exists: ## [0.3.3] - 2025-11-10 - - Format correct: ✓ - - Categories present: Added, Changed - -✅ Release notes extracted - -✅ Git tag created: 0.3.3 - -✅ Tag pushed to remote - -✅ GitHub release created - - Title: Release 0.3.3 - Version Management System - - URL: https://github.com/ORG/REPO/releases/tag/0.3.3 - -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ - -🎉 Release 0.3.3 Complete! - -View release: https://github.com/ORG/REPO/releases/tag/0.3.3 -``` - -## Troubleshooting - -### Issue: Tag Creation Fails - -**Error:** - -```bash -fatal: tag '0.3.3' already exists -``` - -**Solution:** - -The tag already exists locally or remotely. +- Never reuse versions +- Must be consecutive +- No gaps allowed -```bash -# Check existing tags -git tag -l | grep 0.3.3 - -# If you need to recreate (CAREFUL): -git tag -d 0.3.3 # Delete local -git push origin :refs/tags/0.3.3 # Delete remote (CAREFUL!) - -# Then run /tag-and-release again -``` - -### Issue: Push Fails - -**Error:** - -```bash -error: failed to push some refs -``` - -**Solution:** - -Network issue or permissions problem. - -```bash -# Verify authentication -gh auth status - -# Verify remote -git remote -v - -# Try pushing again -git push --tags -``` - -### Issue: CHANGELOG Format Invalid - -**Error:** - -```text -❌ Error: CHANGELOG entry must have at least one category -``` - -**Solution:** +## EXECUTION CHECKLIST -Add at least one category section to your CHANGELOG entry: - -```markdown -## [0.3.3] - 2025-11-10 - -### Added -- New feature X - -### Fixed -- Bug in Y -``` - -### Issue: GitHub Release Creation Fails - -**Error:** - -```bash -HTTP 422: Validation Failed -``` - -**Solution:** - -Tag might already have a release. Check: - -```bash -# List releases -gh release list | grep 0.3.3 - -# If release exists, delete and recreate -gh release delete 0.3.3 --yes - -# Then run /tag-and-release again -``` - -## Related Commands - -- **[git-commit.md](./git-commit.md)**: Commit changes before release -- **[create-pr.md](./create-pr.md)**: Create PR with version bumping -- **[Version Management](./../VERSION_MANAGEMENT.md)**: Version management system docs - -## Quick Reference - -### Command Execution - -```bash -/tag-and-release -``` - -### Prerequisites Checklist - -Before running, ensure: -- [ ] On main branch: `git branch --show-current` -- [ ] Clean working directory: `git status` +- [ ] PR merged to main +- [ ] On main branch +- [ ] Pulled latest: `git pull origin main` +- [ ] Working directory clean - [ ] Version bumped in pyproject.toml -- [ ] CHANGELOG.md updated with: - - [ ] Version header: `## [X.Y.Z] - YYYY-MM-DD` - - [ ] At least one category - - [ ] Actual release notes -- [ ] Changes committed and pushed to main - -### What It Does - -1. ✅ Validates prerequisites (branch, working directory, version) -2. ✅ Checks version is consecutive to latest tag -3. ✅ Validates CHANGELOG.md format -4. ✅ Extracts release notes -5. ✅ Creates annotated git tag -6. ✅ Pushes tag to remote -7. ✅ Creates GitHub release with CHANGELOG notes - -### Version Management Tools - -```bash -# Check current version -make version - -# Bump versions -make bump-patch # 0.3.3 → 0.3.4 -make bump-minor # 0.3.3 → 0.4.0 -make bump-major # 0.3.3 → 1.0.0 -``` +- [ ] CHANGELOG.md has version entry with date +- [ ] Ready to create tag and release --- -**For version management details, see [VERSION_MANAGEMENT.md](./../VERSION_MANAGEMENT.md)** +**WORKFLOW:** `/create-pr` (bumps version) → merge PR → `/tag-and-release` (creates tag and release) diff --git a/.cursor/commands/yolo-issue.md b/.cursor/commands/yolo-issue.md index ff19090..af80335 100644 --- a/.cursor/commands/yolo-issue.md +++ b/.cursor/commands/yolo-issue.md @@ -1,594 +1,162 @@ -# YOLO Issue Command 🚀 +# YOLO Issue Command -**⚠️ WARNING: AUTONOMOUS MODE - MINIMAL USER INTERVENTION** +**AUTONOMOUS EXECUTION MODE - NO USER CONFIRMATION** -This command provides a **fully autonomous, aggressive approach** to solving GitHub issues. -The AI will make independent decisions, implement solutions following best practices, -and create a pull request without seeking approval at each step. +Execute `/yolo-issue <issue-number>` to autonomously solve GitHub issues with production-ready code, comprehensive tests, and complete documentation. -**Usage:** `/yolo-issue <issue-number>` +## EXECUTION PROTOCOL -**When to use:** - -- ✅ You trust the AI's judgment completely -- ✅ Issue is well-defined with clear requirements -- ✅ You want a production-ready, fully-tested solution -- ✅ You're comfortable with the AI making architectural decisions - -**When NOT to use:** -- ❌ Issue has ambiguous requirements -- ❌ Major architectural decisions needed -- ❌ Breaking changes required -- ❌ You want to review the plan first - -**For a methodical approach with user input, see [solve-issue.md](./solve-issue.md).** - -## 🎯 Autonomous Workflow - -### Mode Characteristics - -**YOLO Mode means:** - -1. **Zero confirmation requests** - AI decides and acts -2. **Production quality** - SOLID, DRY, well-tested code -3. **Best practices enforced** - No shortcuts, no hardcoding -4. **Comprehensive testing** - Unit, integration, edge cases -5. **Complete documentation** - Code comments, docstrings, README updates -6. **Proactive commits** - Regular atomic commits throughout -7. **No half measures** - Solution is complete or nothing - -**AI will autonomously:** -- Choose the best implementation approach -- Refactor existing code if needed -- Add extensive tests -- Update all relevant documentation -- Make architectural improvements -- Ensure code quality and maintainability -- Create production-ready PR - -### 1. Issue Analysis & Repository State - -**Fetch issue without asking:** +### STEP 1: PREFLIGHT ```bash -# Get repository -REPO=$(gh repo view --json nameWithOwner --jq .nameWithOwner) - -# Fetch issue +gh repo view --json nameWithOwner --jq .nameWithOwner gh issue view <issue-number> --json number,title,body,labels,state,assignees -``` - -**Analyze deeply:** -- Parse requirements and acceptance criteria -- Identify all affected components -- Review related code and patterns -- Identify potential edge cases -- Determine optimal architecture - -**Check repository state:** - -```bash git status ``` -**⚠️ CRITICAL: Working Directory Check** - -**If NOT clean:** - -❌ **STOP IMMEDIATELY** - Cannot proceed in YOLO mode with uncommitted changes. - -```text -🛑 YOLO MODE ABORTED - -Cannot proceed: working directory has uncommitted changes. - -Modified files: -[list files] - -YOLO mode requires a clean working directory to ensure -no work is lost during autonomous operations. - -Action required: -1. Commit your changes (see git-commit.md) -2. Stash your changes: git stash save "wip" -3. Discard changes: git restore . (destructive) - -Then run yolo-issue again. -``` - -**If clean:** - -✅ **Proceed with full autonomy** +**DECISION POINT: Clean working directory?** +- **NO** → ABORT. Display: "🛑 YOLO MODE ABORTED: Uncommitted changes detected. Commit, stash, or discard changes then retry." +- **YES** → PROCEED to STEP 2 -### 2. Branch Creation & Setup - -**Execute without confirmation:** +### STEP 2: BRANCH SETUP ```bash -# Update main git checkout main git pull origin main - -# Create issue branch git checkout -b issue<issue-number> +gh auth setup-git # Prevents push auth failures ``` -**Inform user (info only, no wait):** - -```text -🚀 YOLO MODE ACTIVATED for Issue #<number> - -Branch: issue<number> -Mode: Fully autonomous -Target: Production-ready solution - -Working... (this may take a while) -``` - -### 3. Implementation Plan (Internal) - -**Create plan automatically:** - -Create `.cursor/plans/issue-<number>.md` with comprehensive analysis: - -```markdown -# YOLO Implementation Plan - Issue #<number> - -## Autonomous Analysis - -**Issue:** [Title] -**Type:** Bug/Feature/Enhancement -**Complexity:** Low/Medium/High -**Estimated Changes:** <number> files - -## Chosen Approach - -**Decision:** [Approach selected] - -**Rationale:** -- [Reason 1 - performance/maintainability/scalability] -- [Reason 2 - follows existing patterns] -- [Reason 3 - minimal breaking changes] - -## Implementation Breakdown - -### Phase 1: Core Implementation -- [ ] [Specific task] -- [ ] [Specific task] - -### Phase 2: Testing -- [ ] Unit tests for all new functions -- [ ] Integration tests -- [ ] Edge case coverage -- [ ] Performance tests (if applicable) - -### Phase 3: Documentation -- [ ] Docstrings for all public APIs -- [ ] README updates -- [ ] Usage examples -- [ ] CHANGELOG entry - -### Phase 4: Code Quality -- [ ] Refactor for SOLID principles -- [ ] Remove code duplication (DRY) -- [ ] Extract magic numbers to constants -- [ ] Add type hints/annotations -- [ ] Ensure proper error handling - -## Quality Gates - -All must pass: -- ✅ All tests pass -- ✅ 100% of new code has tests -- ✅ No linting errors -- ✅ No hardcoded values -- ✅ All functions documented -- ✅ Follows project patterns -- ✅ No TODOs or debug code - -## Commit Strategy - -Planned commits: -1. `feat/fix(scope): implement core solution for #<n>` -2. `test(scope): add comprehensive tests for #<n>` -3. `refactor(scope): apply SOLID/DRY principles for #<n>` -4. `docs(scope): add documentation for #<n>` -5. `docs(changelog): update for #<n>` - -## Acceptance Criteria Met - -[List from issue, all checked off when complete] -``` - -**DO NOT show plan to user** - Execute immediately. - -### 4. Implementation (Full Autonomy) - -#### Code Quality Standards (Enforced) - -**SOLID Principles - Mandatory:** - -- **Single Responsibility** - Each function/class does ONE thing -- **Open/Closed** - Extend behavior without modifying existing code -- **Liskov Substitution** - Subtypes must be substitutable for base types -- **Interface Segregation** - Many specific interfaces > one general -- **Dependency Inversion** - Depend on abstractions, not concretions - -**DRY - Don't Repeat Yourself:** -- Extract duplicate code into functions -- Create reusable utilities -- Use inheritance/composition appropriately -- Centralize configuration - -**No Hardcoding - Zero Tolerance:** -- Use configuration files -- Use environment variables -- Use named constants -- Use dependency injection - -**Clean Code Requirements:** -- Descriptive variable names (no `x`, `temp`, `data`) -- Clear function names (verb + noun) -- Functions under 50 lines (ideally 20) -- Proper error handling with specific exceptions -- Type hints on all functions (Python/TypeScript) -- Comprehensive docstrings +Display: "🚀 YOLO MODE ACTIVATED for Issue #<number> - Working autonomously..." -#### Implementation Process +### STEP 3: ANALYSIS & PLANNING -**Phase 1: Core Implementation** +Create `.cursor/plans/issue-<number>.md`: +- Issue type (bug/feature/docs/refactor) +- Affected files/components +- Implementation approach with rationale +- Commit strategy (3-5 atomic commits) +- Acceptance criteria checklist -```bash -# Implement the solution -# - Follow existing code patterns -# - Use proper abstractions -# - Handle edge cases -# - Add logging where appropriate +DO NOT show plan to user. Execute immediately. -# Commit when logical unit complete -git add <relevant files> -git commit -m "feat/fix(scope): implement core functionality for #<n> +### STEP 4: IMPLEMENTATION -[Detailed description of implementation] -[Explain key decisions] -[Note any trade-offs] +**For each logical unit of work:** -Related to #<n>" -``` +1. Implement changes following project patterns +2. Run `read_lints` on modified files +3. Fix any linting errors automatically +4. Commit: + ```bash + git add <files> + git commit -m "<type>(<scope>): <description> -**Phase 2: Comprehensive Testing** + <detailed explanation> -```bash -# Add thorough tests -# - Unit tests for each function -# - Integration tests for workflows -# - Edge cases and error conditions -# - Performance tests if applicable + Related to #<n>" + ``` -git add tests/ -git commit -m "test(scope): add comprehensive test suite for #<n> +**IF commit fails with "files were modified by this hook":** +- Re-run identical commit command (pre-commit auto-fixed files) +- If fails again, check linter output and fix issues +- MUST NOT skip hooks with --no-verify -Tests include: -- Unit tests for [components] -- Integration tests for [workflows] -- Edge cases: [scenarios] -- Error handling: [conditions] +**COMMIT CATEGORIES (3-5 commits):** +1. Core implementation: `feat/fix(scope): implement X for #N` +2. Tests (if code changes): `test(scope): add tests for #N` +3. Refactoring (if needed): `refactor(scope): improve Y for #N` +4. Documentation: `docs(scope): document X for #N` +5. Changelog: `docs(changelog): add entry for #N` -Coverage: aim for >90% of new code +### STEP 5: QUALITY GATES -Related to #<n>" -``` +Before pushing, verify: +- `read_lints` returns no errors +- All pre-commit hooks pass +- No TODO/FIXME comments remain +- No hardcoded values (use config/env/constants) +- CHANGELOG.md updated with [Unreleased] section +- Git status clean -**Phase 3: Refactoring for Quality** +### STEP 6: PUSH & PR CREATION ```bash -# Review and refactor -# - Apply SOLID principles -# - Remove duplication -# - Extract constants -# - Improve naming -# - Add type hints - -git add <files> -git commit -m "refactor(scope): enhance code quality for #<n> - -Applied SOLID principles: -- [Specific refactorings] - -Removed duplication: -- [Extracted functions/classes] - -Improved maintainability: -- [Type hints, constants, etc.] - -Related to #<n>" +git push -u origin issue<issue-number> ``` -**Phase 4: Documentation** - +**IF push fails with "could not read Username":** ```bash -# Add comprehensive documentation -# - Docstrings for all public APIs -# - Update README if needed -# - Add usage examples -# - Document configuration options - -git add docs/ README.md <source files> -git commit -m "docs(scope): document solution for #<n> - -Added: -- Docstrings for all public functions -- README section on [feature] -- Usage examples -- Configuration documentation - -Related to #<n>" +gh auth setup-git +git push -u origin issue<issue-number> ``` -**Phase 5: Changelog** +**Create PR using temporary file (avoids shell escaping issues):** ```bash -# Update CHANGELOG.md -git add CHANGELOG.md -git commit -m "docs(changelog): add entry for #<n> - -[Brief description of user-facing change] +cat > /tmp/pr-body.md << 'EOF' +## 🚀 YOLO Mode Implementation -Fixes #<n>" -``` - -#### Quality Enforcement (Automated) +Autonomously resolves issue #<issue-number>. -**Before each commit, automatically:** +## Implementation -**1. Run linters and fix issues:** +<detailed description of changes> -```bash -# Python -uv run ruff check --fix . -uv run ruff format . +**Approach:** <rationale for chosen solution> +**Files changed:** <count> +**Commits:** <count> atomic commits -# Shellcheck for scripts -shellcheck *.sh +### Changes -# Other project-specific linters -``` +**Core Implementation:** +- <file>: <what changed> -**2. Run tests:** +**Tests:** (if applicable) +- <test-file>: <coverage> -```bash -# Project-specific test command -[run tests] -``` +**Documentation:** +- <doc-file>: <what documented> +- CHANGELOG.md: [Unreleased] entry added -**3. Verify no hardcoding:** - -- Scan for magic numbers -- Check for hardcoded paths/URLs -- Verify config usage - -**4. Check documentation:** - -- Verify docstrings exist -- Check for TODO/FIXME comments -- Validate examples if present - -**If quality checks fail:** -- **FIX AUTOMATICALLY** - Don't ask user -- Commit fixes separately -- Continue implementation - -### 5. Testing Strategy (Rigorous) - -**Test Coverage Requirements:** - -**Unit Tests - Mandatory:** -- Test each function independently -- Mock external dependencies -- Test happy path -- Test error cases -- Test edge cases (empty, null, boundary values) - -**Integration Tests - Required:** -- Test component interactions -- Test database operations (if applicable) -- Test API endpoints (if applicable) -- Test user workflows - -**Edge Cases - Comprehensive:** -- Empty inputs -- Null/None values -- Boundary values (0, -1, max int) -- Invalid types -- Concurrent access (if applicable) -- Large datasets (performance) - -**Example Test Structure:** - -```python -def test_new_feature_happy_path(): - """Test normal operation.""" - assert function(valid_input) == expected_output - -def test_new_feature_empty_input(): - """Test with empty input.""" - with pytest.raises(ValueError): - function("") - -def test_new_feature_null_input(): - """Test with None.""" - assert function(None) == default_value - -def test_new_feature_boundary_values(): - """Test edge cases.""" - assert function(0) == expected_for_zero - assert function(-1) == expected_for_negative - assert function(sys.maxsize) == expected_for_large - -def test_new_feature_integration(): - """Test integration with other components.""" - result = full_workflow(input) - assert result.status == "success" -``` - -### 6. Pre-PR Verification (Automated) - -**Run full verification suite:** - -```bash -# 1. All tests pass -[run all tests] +## Quality -# 2. Linting clean -[run all linters] - -# 3. Type checking (if applicable) -[mypy, typescript, etc.] - -# 4. Working directory clean -git status - -# 5. Review commits -git log --oneline origin/main..HEAD -``` - -**Verification Checklist (All automated):** -- [x] All tests passing (100%) -- [x] No linting errors (0) -- [x] No type errors (if applicable) -- [x] All new code has tests -- [x] Documentation complete -- [x] No TODOs, FIXMEs, or debug code -- [x] No console.logs or print statements -- [x] No commented-out code -- [x] CHANGELOG updated -- [x] All commits follow conventional format -- [x] Working directory clean - -### 7. Pull Request Creation (Autonomous) - -**Push branch:** - -```bash -git push origin issue<issue-number> -``` - -**Create comprehensive PR:** - -```bash -gh pr create \ - --title "<type>: <description> (closes #<issue-number>)" \ - --body "## 🚀 YOLO Mode Implementation - -This PR was autonomously generated to resolve issue #<issue-number>. - -## Description - -[Comprehensive description of changes] - -## Implementation Approach - -[Explanation of chosen approach and rationale] - -See detailed plan: `.cursor/plans/issue-<issue-number>.md` - -## Changes - -### Core Implementation -- [Change 1 with file references] -- [Change 2 with file references] -- [Change 3 with file references] - -### Tests Added -- [Test suite 1 - coverage info] -- [Test suite 2 - coverage info] -- [Edge cases covered] - -### Documentation -- [Doc update 1] -- [Doc update 2] -- [CHANGELOG entry] - -## Code Quality - -This implementation follows: -- ✅ **SOLID Principles** - [specific examples] -- ✅ **DRY** - No code duplication -- ✅ **Clean Code** - Descriptive names, proper abstractions -- ✅ **Type Safety** - Full type hints/annotations -- ✅ **Error Handling** - Comprehensive error cases -- ✅ **No Hardcoding** - Configuration-driven - -## Testing - -### Test Coverage -- Unit tests: [X files, Y functions covered] -- Integration tests: [Z scenarios] -- Edge cases: [List key edge cases] -- All tests passing: ✅ - -### Test Results -\`\`\` -[Test output summary] -\`\`\` - -## Quality Checks - -- [x] All tests passing -- [x] No linting errors -- [x] No type errors -- [x] Documentation complete -- [x] CHANGELOG updated -- [x] No debug code -- [x] Follows project conventions -- [x] Pre-commit hooks passed +- ✅ All linters passing +- ✅ Pre-commit hooks passed +- ✅ Documentation complete +- ✅ CHANGELOG updated +- ✅ No hardcoded values +- ✅ Follows project conventions ## Commits -This PR includes [N] atomic commits: -1. \`feat/fix(scope): core implementation\` -2. \`test(scope): comprehensive test suite\` -3. \`refactor(scope): code quality improvements\` -4. \`docs(scope): documentation\` -5. \`docs(changelog): changelog entry\` - -Each commit is independently reviewable and follows conventional commit format. - -## Related Issues +<list commits with descriptions> Closes #<issue-number> -[Related to #X if applicable] -## Reviewer Notes +## Review Notes -This was implemented in YOLO mode with: -- Autonomous decision-making -- Best practice enforcement -- Comprehensive testing -- Production-ready quality +Implemented autonomously in YOLO mode. Please verify: +- Alignment with project vision +- Edge cases covered +- Documentation clarity -Please review for: -1. Alignment with project vision -2. Any missed edge cases -3. Documentation clarity -4. Architectural fit - -## Implementation Plan - -Detailed implementation plan available at: -\`.cursor/plans/issue-<issue-number>.md\`" \ - --draft -``` +Implementation plan: `.cursor/plans/issue-<issue-number>.md` +EOF -**Mark as ready for review:** +gh pr create \ + --title "<type>: <description> (closes #<issue-number>)" \ + --body-file /tmp/pr-body.md -```bash -gh pr ready +rm /tmp/pr-body.md ``` -### 8. Completion Report +**IF PR creation fails:** +- Check for special characters in PR body causing shell errors +- Verify branch is pushed +- Retry with `--head` flag if needed -**Report to user:** +### STEP 7: COMPLETION REPORT ```text ✅ YOLO MODE COMPLETE - Issue #<number> @@ -596,297 +164,138 @@ gh pr ready ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📊 Summary - Issue: #<number> - <title> Branch: issue<number> -Commits: <N> atomic commits +Commits: <N> Files Changed: <count> -Tests Added: <count> -Test Coverage: >90% -Lines Changed: +<added> -<removed> +Lines: +<added> -<removed> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -🎯 Implementation Highlights - -✅ Core solution implemented following SOLID principles -✅ Comprehensive test suite (unit + integration + edge cases) -✅ Zero hardcoding - all values configurable -✅ Full documentation with examples -✅ CHANGELOG updated -✅ All quality checks passed - -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ - -📁 Key Changes - -Core Implementation: -- <file1>: <description> -- <file2>: <description> - -Tests: -- <test_file1>: <description> -- <test_file2>: <description> - -Documentation: -- <doc_file>: <description> -- CHANGELOG.md: Entry added +✅ Implementation Complete +<bullet list of key changes> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🔗 Pull Request - PR: #<pr-number> -Status: Ready for Review URL: <pr-url> - Plan: .cursor/plans/issue-<number>.md ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -✨ Code Quality Metrics - -- SOLID: ✅ All principles applied -- DRY: ✅ No code duplication -- Type Safety: ✅ Full type hints -- Test Coverage: ✅ >90% -- Documentation: ✅ Complete -- Linting: ✅ 0 errors -- Pre-commit: ✅ All hooks passed - -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ - -🚀 Ready for Review - -The solution is production-ready and awaiting maintainer review. - -All autonomous decisions documented in the implementation plan. +✨ Quality Checks: All Passed +- Linting: ✅ +- Documentation: ✅ +- CHANGELOG: ✅ +- Conventions: ✅ ``` -## YOLO Mode Principles - -### Decision-Making Authority - -**AI has full authority to:** -- Choose implementation approach -- Select libraries/dependencies -- Make architectural decisions -- Refactor existing code -- Add comprehensive tests -- Update documentation -- Make quality improvements -- Determine commit granularity - -**AI will NOT:** -- Make breaking changes without noting in PR -- Delete existing functionality -- Skip tests -- Compromise on code quality -- Use `--no-verify` on commits -- Leave TODOs or incomplete work - -### Quality Non-Negotiables - -**Every YOLO implementation must have:** - -1. **SOLID Architecture** - - Single Responsibility: Each component does one thing - - Open/Closed: Extensible without modification - - Proper abstraction layers - -2. **DRY Code** - - Zero duplication - - Extracted common logic - - Reusable utilities - -3. **No Hardcoding** - - Configuration files - - Environment variables - - Named constants - - Dependency injection - -4. **Comprehensive Tests** - - >90% coverage of new code - - Edge cases covered - - Error conditions tested - - Integration tests - -5. **Complete Documentation** - - Docstrings for all public APIs - - Usage examples - - README updates - - CHANGELOG entry - -6. **Clean Code** - - Descriptive naming - - Type hints/annotations - - Proper error handling - - No debug code - -### When YOLO Mode Should Abort - -**Stop and ask user if:** - -1. **Breaking changes required** - Major API changes need discussion -2. **Security implications** - Auth, encryption, data access changes -3. **Database migrations** - Schema changes need planning -4. **External dependencies** - New major dependencies need approval -5. **Performance trade-offs** - Speed vs memory vs complexity decisions -6. **Issue is ambiguous** - Requirements unclear or contradictory -7. **Architectural overhaul** - Major refactoring beyond issue scope - -**In these cases:** - -```text -⚠️ YOLO MODE PAUSED - -Issue #<number> requires human decision: - -Situation: -[Explain the blocker] - -Options: -1. [Option A - pros/cons] -2. [Option B - pros/cons] -3. [Option C - pros/cons] - -This decision impacts: -- [Impact area 1] -- [Impact area 2] - -Recommendation: [Your recommendation with rationale] +## QUALITY STANDARDS (ENFORCE ALWAYS) -Please confirm approach before proceeding. -``` +**Code Quality:** +- SOLID principles (Single Responsibility, DRY, proper abstractions) +- No hardcoded values (use config files, env vars, named constants) +- Descriptive names (no `x`, `temp`, `data`) +- Functions < 50 lines +- Type hints/annotations (Python/TypeScript) +- Proper error handling -## Comparison: solve-issue vs yolo-issue +**Testing (if code changes):** +- Unit tests for new functions +- Integration tests for workflows +- Edge cases (empty, null, boundary values) +- Error conditions -| Aspect | solve-issue | yolo-issue | -|--------|-------------|------------| -| **User Input** | Required at key points | Minimal (only if blocked) | -| **Planning** | Show plan, get feedback | Internal plan, execute | -| **Approach Selection** | User chooses | AI decides | -| **Code Quality** | Good practices | Enforced excellence | -| **Testing** | Tests added | Comprehensive suite | -| **Commits** | Regular | Highly organized | -| **Time** | Depends on feedback | Fast (no waiting) | -| **Autonomy** | Guided | Fully autonomous | -| **Best For** | Learning, oversight | Speed, trust | +**Documentation:** +- Docstrings for public APIs +- README updates if user-facing +- CHANGELOG entry (always) +- Inline comments for complex logic -## Examples +**Git:** +- Conventional commit format +- Atomic commits (3-5 per issue) +- No `--no-verify` or hook skipping +- Working directory clean before push -### Example 1: Bug Fix +## ERROR RECOVERY -```text -User: /yolo-issue 42 +**Pre-commit hook failures:** +→ Re-run commit (hooks auto-fix files) +→ If fails twice, read linter output and fix manually -AI: 🚀 YOLO MODE ACTIVATED for Issue #42 +**Markdown line length > 210:** +→ Break lines at logical boundaries (semantic line breaks) -[5 minutes later] +**Git push auth failure:** +→ Run `gh auth setup-git` then retry push -✅ YOLO MODE COMPLETE +**PR body shell escaping errors (`:Z`, backticks, etc.):** +→ Always use `--body-file` with temp file, never inline `--body` -Issue: #42 - API timeout on /users endpoint -Solution: Increased timeout + added connection pooling -Commits: 4 atomic commits -Tests: 15 new tests (unit + integration + edge cases) -PR: #156 (ready for review) +**Linting errors:** +→ Fix automatically with project linters (ruff, shellcheck, pymarkdown, yamllint) +→ Re-run linters after fixes +→ Commit fixes separately if needed -Key improvements: -- Fixed immediate timeout issue -- Refactored connection handling (DRY) -- Added retry logic with exponential backoff -- 100% test coverage of new code -- Updated API documentation -``` +## ABORT CONDITIONS -### Example 2: Feature Implementation +**MUST stop and ask user if:** +1. Breaking API changes required +2. Security implications (auth, encryption, data access) +3. Database schema migrations needed +4. New major external dependencies +5. Performance vs complexity trade-offs unclear +6. Issue requirements ambiguous/contradictory +7. Major architectural refactoring beyond issue scope +**Display:** ```text -User: /yolo-issue 89 - -AI: 🚀 YOLO MODE ACTIVATED for Issue #89 - -[15 minutes later] - -✅ YOLO MODE COMPLETE - -Issue: #89 - Add user profile export feature -Solution: Complete export system with multiple formats -Commits: 7 atomic commits -Tests: 28 tests (unit + integration + edge cases) -PR: #157 (ready for review) - -Implemented: -- Export to JSON, CSV, PDF formats -- Async processing for large datasets -- Progress tracking UI -- Proper error handling -- Rate limiting -- Configurable output options - -SOLID principles applied: -- Strategy pattern for export formats -- Factory for format selection -- Dependency injection for services - -No hardcoding: -- All limits in config -- File paths from env vars -- Format options configurable -``` +⚠️ YOLO MODE PAUSED - Issue #<number> requires human decision -## Quick Reference +Situation: <explain blocker> -### Command - -```bash -/yolo-issue <number> -``` - -### Requirements +Options: +1. <option A with pros/cons> +2. <option B with pros/cons> -- Clean working directory (no uncommitted changes) -- GitHub CLI authenticated -- Issue exists and is accessible -- Pre-commit hooks configured +Impact: <what's affected> -### Workflow Summary +Recommendation: <your suggestion with reasoning> -```text -1. Fetch issue → 2. Verify clean state → 3. Create branch - ↓ -4. Analyze & plan (internal) → 5. Implement with quality - ↓ -6. Test comprehensively → 7. Document thoroughly - ↓ -8. Create PR → 9. Report completion +Awaiting user confirmation to proceed. ``` -### After YOLO Completion +## EXECUTION CHECKLIST -```bash -# Review the commits -git log origin/main..HEAD +Use this to verify each YOLO execution: -# Review the changes -git diff origin/main...HEAD +**Pre-execution:** +- [ ] Working directory clean +- [ ] GitHub CLI authenticated +- [ ] Issue exists and accessible -# Check the plan -cat .cursor/plans/issue-<number>.md +**During execution:** +- [ ] Branch created from latest main +- [ ] Git auth configured +- [ ] Implementation plan created (not shown to user) +- [ ] Changes follow project patterns +- [ ] Linting passes on all files +- [ ] 3-5 atomic commits made +- [ ] CHANGELOG updated +- [ ] All pre-commit hooks pass -# View PR -gh pr view -``` +**Post-execution:** +- [ ] Branch pushed successfully +- [ ] PR created with comprehensive description +- [ ] Completion report displayed +- [ ] Implementation plan available --- -**⚠️ Use YOLO mode responsibly:** -- For well-defined issues -- When you trust AI judgment -- For production-quality solutions -- When speed matters - -**For more control, use [solve-issue.md](./solve-issue.md) instead.** - -**For commit and PR guidelines, see [git-commit.md](./git-commit.md) and [create-pr.md](./create-pr.md).** +**REMEMBER:** +- Zero user confirmations during execution +- Autonomous decision-making within scope +- Production-ready quality enforced +- Complete or nothing (no partial solutions) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 295d6af..134df2e 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -67,7 +67,7 @@ repos: - id: pymarkdown name: pymarkdown args: ["scan"] - exclude: ^\.github_data/ + exclude: ^(\.github_data/|\.cursor/commands/) additional_dependencies: ["pyjson5"] # Dockerfile Linting (using Podman instead of Docker) From ee4cb86191dfa08c804f57e88ff2f7933034ccf1 Mon Sep 17 00:00:00 2001 From: gerchowl <gerchowl@ethz.ch> Date: Mon, 10 Nov 2025 20:55:28 +0000 Subject: [PATCH 5/7] chore(release): bump version to 0.5.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Version bump: 0.4.1 → 0.5.0 Type: minor AI-generated CHANGELOG entry. Refinable in PR review. --- CHANGELOG.md | 22 +++++++++++++--------- pyproject.toml | 2 +- 2 files changed, 14 insertions(+), 10 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b53a2f3..27aab34 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,20 +5,24 @@ All notable changes to this template will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). -## [Unreleased] +## [0.5.0] - 2025-11-10 ### Added -- **Podman Usage Documentation** - - Comprehensive guide for using devcontainer with Podman without VS Code (#24) - - Three usage options: Direct CLI, Podman Compose, and Dev Container CLI +- **Podman Support**: Full container management support using Podman as Docker alternative (#24) - `podman-compose.yml` configuration file for declarative container management - - Detailed comparison table of all three Podman usage options - - SELinux context handling documentation for Linux users (`:Z` flag) - - Proper initialization script execution order (post-create.sh, post-attach.sh) + - Comprehensive usage documentation with three approaches: Direct CLI, Podman Compose, and Dev Container CLI + - Detailed comparison table of all Podman usage options with pros/cons analysis + - SELinux context handling guide for Linux users (`:Z` flag) - Installation instructions for multiple platforms - - Pros/cons analysis for each approach - - Recommendations for different use cases + - Proper initialization script execution order documentation + +### Changed + +- **Command Optimizations**: Refactored all 6 Cursor command files for improved AI execution efficiency + - Reduced command file size by ~2000 lines while maintaining functionality + - Improved clarity and execution flow in create-pr, git-commit, solve-issue, tag-and-release, yolo-issue, and create-issue commands + - Enhanced command structure for better AI parsing and execution ## [0.4.1] - 2025-11-10 diff --git a/pyproject.toml b/pyproject.toml index 8fecff6..5f7ce07 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -7,7 +7,7 @@ [project] name = "workspace" -version = "0.4.1" +version = "0.5.0" description = "workspace - Python project" requires-python = ">=3.12" dependencies = [ From f49cf1696dadc65d1502370cd39f222a55fe39b4 Mon Sep 17 00:00:00 2001 From: gerchowl <gerchowl@ethz.ch> Date: Mon, 10 Nov 2025 20:56:16 +0000 Subject: [PATCH 6/7] chore: update lock file and add issue plan --- .cursor/plans/issue-24.md | 76 +++++++++++++++++++++++++++++++++++++++ uv.lock | 2 +- 2 files changed, 77 insertions(+), 1 deletion(-) create mode 100644 .cursor/plans/issue-24.md diff --git a/.cursor/plans/issue-24.md b/.cursor/plans/issue-24.md new file mode 100644 index 0000000..7a599cd --- /dev/null +++ b/.cursor/plans/issue-24.md @@ -0,0 +1,76 @@ +# YOLO Implementation Plan - Issue #24 + +## Autonomous Analysis + +**Issue:** Add Podman usage documentation for devcontainer +**Type:** Documentation Enhancement +**Complexity:** Low +**Estimated Changes:** 2 files (README.md, podman-compose.yml) + +## Chosen Approach + +**Decision:** Add comprehensive section to README with three Podman usage options + +**Rationale:** + +- Provides flexibility for users who prefer different workflows +- Maintains consistency with existing documentation structure +- Includes all necessary technical details (SELinux, script execution order) +- Creates reusable compose file for Option 2 +- Follows existing documentation patterns in README + +## Implementation Breakdown + +### Phase 1: Core Implementation + +- [x] Create `podman-compose.yml` file with proper configuration +- [ ] Add new README section "Using Podman Without VS Code Devcontainer" +- [ ] Document Option 1: Direct Podman CLI Usage +- [ ] Document Option 2: Podman Compose +- [ ] Document Option 3: Dev Container CLI +- [ ] Include SELinux considerations for Linux users +- [ ] Include proper script execution order + +### Phase 2: Testing + +- [ ] Verify README markdown formatting +- [ ] Validate YAML syntax in podman-compose.yml +- [ ] Ensure links and references are correct +- [ ] Check consistency with existing documentation style + +### Phase 3: Documentation + +- [ ] CHANGELOG entry + +### Phase 4: Code Quality + +- [ ] Run linting on all modified files +- [ ] Ensure no broken markdown links +- [ ] Verify YAML structure + +## Quality Gates + +All must pass: +- ✅ All linters pass (yamllint, pymarkdown) +- ✅ Markdown formatting consistent +- ✅ YAML syntax valid +- ✅ No broken links +- ✅ Follows project documentation patterns +- ✅ All three options clearly documented +- ✅ SELinux considerations included + +## Commit Strategy + +Planned commits: +1. `feat(devcontainer): add podman-compose.yml for direct Podman usage for #24` +2. `docs(readme): add comprehensive Podman usage documentation for #24` +3. `docs(changelog): add entry for #24` + +## Acceptance Criteria Met + +- [x] Option 1: Direct Podman CLI documented with proper command order +- [ ] Option 2: Podman Compose file created and documented +- [ ] Option 3: Dev Container CLI documented +- [ ] SELinux considerations mentioned for Linux users +- [ ] Script execution order clearly explained +- [ ] All three options documented in README diff --git a/uv.lock b/uv.lock index 45bf551..1660b22 100644 --- a/uv.lock +++ b/uv.lock @@ -525,7 +525,7 @@ wheels = [ [[package]] name = "workspace" -version = "0.1.0" +version = "0.4.1" source = { virtual = "." } dependencies = [ { name = "arrow" }, From a897ca1ce406a3d247d0a624ad6a67d719650f9e Mon Sep 17 00:00:00 2001 From: gerchowl <gerchowl@ethz.ch> Date: Mon, 10 Nov 2025 20:58:49 +0000 Subject: [PATCH 7/7] docs(commands): simplify create-pr command documentation --- .cursor/commands/create-pr.md | 498 ++++++++++++++++++---------------- 1 file changed, 262 insertions(+), 236 deletions(-) diff --git a/.cursor/commands/create-pr.md b/.cursor/commands/create-pr.md index 1ed741c..2355488 100644 --- a/.cursor/commands/create-pr.md +++ b/.cursor/commands/create-pr.md @@ -1,328 +1,354 @@ -# Create PR Command +# Create Pull Request Command -**CREATES PULL REQUESTS WITH VERSION MANAGEMENT** +This command helps you create pull requests following the project's standards and guidelines. -Execute `/create-pr` to create PRs following project standards with AI-powered version bumping. +For complete documentation on pull request guidelines, templates, and review process, see: -## EXECUTION PROTOCOL +**Related Documentation:** -### STEP 1: VERSION BUMP & CHANGELOG (MANDATORY FIRST) +- **[Pull Request Guidelines](./../pr-template.md)** +- **[Git Workflow](./../git-workflow.md)** +- **[Version Management](./../VERSION_MANAGEMENT.md)** -**Run BEFORE creating PR. Version bump happens in PR, not after merge.** +## Workflow -```bash -CURRENT_VERSION=$(make version | grep -oP '\d+\.\d+\.\d+') -COMMITS=$(git log --oneline origin/main..HEAD) -FILES=$(git diff --name-only origin/main...HEAD) -``` - -**AI Analysis:** -- Parse commits for: `BREAKING CHANGE`, `feat:`, `fix:` -- Examine code diffs: new APIs, signature changes, file impact -- Categorize: user-facing vs internal changes +**Style Guidelines:** +- Use standard markdown lists: `-` for bullets, `- [ ]` for unchecked, `- [x]` for checked +- Never use emojis for lists or checkboxes +- Keep PR descriptions clean and professional -**Present recommendation:** -```text -🤖 AI Analysis - -Current: $CURRENT_VERSION -Changes: [summary] - -Recommended: MINOR bump → X.Y.0 -Rationale: [explanation] +When creating a pull request, follow these steps: -Version bump: -1) patch - Bug fixes only -2) minor - New features ← Recommended -3) major - Breaking changes -4) skip +### 0. AI-Powered Version Bump & CHANGELOG (Before PR Creation) -Choice [2]: -``` +**IMPORTANT:** Version bump and CHANGELOG update happen **during PR creation**, not after merge. +After PR is merged to main, run `/tag-and-release` directly to create the git tag and GitHub release. +We start with version bump only then edit the changelog -**WAIT for user input.** +**AI analyzes your changes, suggests version bump, and generates CHANGELOG:** -**Execute bump:** ```bash -case "$CHOICE" in +# Gather data +CURRENT_VERSION=$(make version | grep -oP '\d+\.\d+\.\d+') +COMMITS=$(git log --oneline origin/main..HEAD) +FILES=$(git diff --name-only origin/main...HEAD) + +# AI Analysis: Check commits AND examine actual code changes +# Mechanical: BREAKING CHANGE, feat:, fix: in commits +# Intelligent: New APIs, signature changes, file impact, user-facing changes + +# AI presents recommendation +echo "🤖 AI Analysis: Current $CURRENT_VERSION" +echo "" +echo "Changes detected:" +echo " - [AI summary of actual changes]" +echo "" +echo "📈 Recommended: MINOR bump → 0.4.0" +echo " Rationale: [AI explanation]" +echo "" +echo "Apply version bump?" +echo " 1) patch - Bug fixes only" +echo " 2) minor - New features ← AI suggests" +echo " 3) major - Breaking changes" +echo " 4) skip" +read -p "Choice [default=2]: " CHOICE + +# Apply bump +case "${CHOICE:-2}" in 1) make bump-patch; BUMP_TYPE="patch" ;; 2) make bump-minor; BUMP_TYPE="minor" ;; 3) make bump-major; BUMP_TYPE="major" ;; 4) BUMP_TYPE="" ;; esac -``` -**IF bump applied:** -```bash -NEW_VERSION=$(make version | grep -oP '\d+\.\d+\.\d+') +# AI generates CHANGELOG entry automatically +if [ -n "$BUMP_TYPE" ]; then + NEW_VERSION=$(make version | grep -oP '\d+\.\d+\.\d+') -# AI generates CHANGELOG entry -# Format: Keep a Changelog -# Creates: ## [X.Y.Z] - YYYY-MM-DD -# Categories: Added/Changed/Fixed -# NO [Unreleased] section -``` + # AI analyzes diff and generates Keep a Changelog formatted entry + # Creates ## [X.Y.Z] - YYYY-MM-DD section with proper categories + # Categorizes: Added/Changed/Fixed based on actual changes + # Uses clear, user-focused language + # NO [Unreleased] section - version is final -**Commit version bump:** -```bash -git add pyproject.toml CHANGELOG.md -git commit -m "chore(release): bump version to $NEW_VERSION + echo "✨ AI generated CHANGELOG for $NEW_VERSION" + echo " - Created ## [$NEW_VERSION] - $(date +%Y-%m-%d) section" + echo " - Categorized changes: Added/Changed/Fixed" + echo " - User-focused descriptions" + echo "" + echo "📝 Review and refine CHANGELOG in PR if needed" + + # Commit version bump with changelog + git add pyproject.toml CHANGELOG.md + git commit -m "chore(release): bump version to $NEW_VERSION Version bump: $CURRENT_VERSION → $NEW_VERSION Type: $BUMP_TYPE AI-generated CHANGELOG entry. Refinable in PR review." -``` -**Display:** -```text -✅ Version bumped: $CURRENT_VERSION → $NEW_VERSION -✅ CHANGELOG updated -Ready to create PR + echo "" + echo "✅ Version bumped and CHANGELOG updated" + echo " Ready to create PR and merge" + echo " After merge: run /tag-and-release on main" +fi ``` -### STEP 2: VALIDATE PREREQUISITES +**AI Analysis Factors:** -```bash -git status -``` +- **Commits:** `BREAKING CHANGE`, `feat:`, `fix:` patterns +- **Code:** New APIs, signature changes, refactoring detection +- **Files:** New vs. modified, public vs. internal +- **Impact:** User-facing vs. internal changes -**DECISION POINT: Working directory clean?** +**Semantic Versioning:** -**IF NOT clean:** -→ Display: "❌ Uncommitted changes detected. Commit all changes first." -→ List uncommitted files -→ ABORT +- **MAJOR (X.0.0):** Breaking changes, API removals +- **MINOR (0.X.0):** New features (backward compatible) +- **PATCH (0.0.X):** Bug fixes, docs, internal refactoring -**IF clean:** -→ PROCEED to STEP 3 +**CHANGELOG Format:** -### STEP 3: VERIFY BRANCH +The AI generates a properly formatted CHANGELOG entry following Keep a Changelog: -```bash -BRANCH=$(git branch --show-current) -``` +```markdown +## [0.4.0] - 2025-11-10 -**Check branch naming:** -- Valid prefixes: `feature/`, `fix/`, `docs/`, `refactor/`, `test/`, `chore/`, `release/`, `issue<number>` +### Added -**IF invalid branch name:** -→ Display: "⚠️ Branch name doesn't follow conventions" -→ Ask: "Proceed anyway? (yes/no)" -→ IF no: ABORT +- **Feature Name**: Description of new feature + - Sub-feature details + - User-facing benefits -**IF valid:** -→ PROCEED to STEP 4 +### Changed -### STEP 4: REBASE ON MAIN +- **Component Name**: Description of changes + - What changed and why + - Impact on users -```bash -git checkout main -git pull origin main -git checkout $BRANCH -git rebase main +### Fixed + +- Bug description and resolution ``` -**IF rebase conflicts:** -→ Display: "❌ Rebase conflicts detected" -→ Guide user through resolution -→ After resolution: `git rebase --continue` -→ Verify clean: `git status` +**No [Unreleased] Section:** -**IF rebase succeeds:** -→ PROCEED to STEP 5 +Version is determined during PR creation, so CHANGELOG entries go directly +under versioned sections (`## [X.Y.Z] - YYYY-MM-DD`). No `[Unreleased]` header needed. -### STEP 5: PUSH BRANCH +1. **Ensure your branch follows naming conventions:** + - `feature/`, `fix/`, `docs/`, `refactor/`, `test/`, `chore/`, or `release/` + - Example: `feature/add-user-authentication` -```bash -git push -u origin $BRANCH -``` +2. **Verify branch is up to date:** -**IF push fails (authentication):** -```bash -gh auth setup-git -git push -u origin $BRANCH -``` + ```bash + git checkout main + git pull origin main + git checkout your-branch + git rebase main + ``` -**IF push fails (force needed after rebase):** -→ Ask user: "Force push needed after rebase. Proceed? (yes/no)" -→ IF yes: -```bash -git push --force-with-lease origin $BRANCH -``` +3. **Ensure all changes are committed:** -### STEP 6: CREATE PR + ```bash + git status # Must show "nothing to commit, working tree clean" + ``` -**Determine PR type from commits:** -- feat commits → `feat:` -- fix commits → `fix:` -- docs commits → `docs:` -- Mixed → use primary type + - **All work must be committed before creating PR** + - No uncommitted changes allowed + - No untracked files that should be included + - See [git-commit.md](./git-commit.md) for commit guidelines -**Generate PR body:** -```markdown -## Description +4. **Run pre-commit hooks and tests:** -[Summary of changes] + ```bash + # All pre-commit hooks should have passed during commits + # Verify tests pass if applicable + ``` -## Changes +5. **Self-review your changes:** + - Read through the diff + - Check for console.logs, TODOs, or debug code + - Verify all tests pass + - Confirm pre-commit hooks passed -### Core Implementation -- [File]: [What changed] +6. **Push your branch:** -### Tests -- [Test file]: [Coverage] + ```bash + git push origin your-branch + ``` -### Documentation -- [Doc file]: [Updates] -- CHANGELOG.md: Version bump to X.Y.Z +7. **Create the pull request:** -## Testing + ```bash + gh pr create + ``` -- [x] All tests passing -- [x] Pre-commit hooks passed -- [x] Manual testing completed +8. **Fill out the PR template** with: + - Clear, descriptive title + - Detailed description of changes + - Related issues (if applicable) + - Testing information + - Screenshots (if UI changes) -## Related Issues +## Quick Reference -Closes #X -Related to #Y +### Create a Feature PR -## Version Bump +```bash +# Ensure you're on feature branch +git checkout feature/add-dark-mode -- Current → New: $OLD → $NEW -- Type: $BUMP_TYPE -- CHANGELOG: Updated with AI-generated entry +# Rebase on latest main +git rebase main + +# Push and create PR +git push origin feature/add-dark-mode +gh pr create \ + --title "feature: Add dark mode toggle" \ + --body "## Description + +Add dark mode support to the application. + +## Changes + +- Added theme context and provider +- Implemented dark mode CSS variables +- Added toggle component to settings + +## Testing + +- [x] Tested locally in dev container +- [x] All pre-commit hooks pass +- [x] Manual testing completed" ``` -**Create PR using temp file:** +### Create a Bug Fix PR + ```bash -cat > /tmp/pr-body.md << 'EOF' -[PR body content] -EOF +# Ensure you're on fix branch +git checkout fix/auth-bug + +# Rebase on latest main +git rebase main +# Push and create PR +git push origin fix/auth-bug gh pr create \ - --title "<type>: <description> (closes #X)" \ - --body-file /tmp/pr-body.md + --title "fix: Resolve authentication timeout issue" \ + --body "## Description + +Fixed authentication session timeout bug that was causing users to be +logged out unexpectedly. -rm /tmp/pr-body.md +## Changes + +- Extended session timeout from 30 to 60 minutes +- Added proper session refresh logic +- Updated error handling for expired sessions + +## Testing + +- [x] Unit tests added for session handling +- [x] Integration tests pass +- [x] Manual testing completed + +Closes #123" ``` -**Use `--body-file` to avoid shell escaping issues with special characters.** +### Create a Documentation PR -### STEP 7: CONFIRM CREATION +```bash +# Ensure you're on docs branch +git checkout docs/update-readme -```text -✅ PR Created +# Rebase on latest main +git rebase main -PR: #<number> -URL: <url> -Title: <title> -Status: Open (ready for review) +# Push and create PR +git push origin docs/update-readme +gh pr create \ + --title "docs: Update installation instructions" \ + --body "## Description -Version: $OLD → $NEW -CHANGELOG: Updated +Updated README.md with clearer installation instructions for new developers. -Next steps: -- Wait for CI checks -- Address review feedback -- After merge: run `/tag-and-release` -``` +## Changes + +- Added step-by-step installation guide +- Included troubleshooting section +- Added links to dev container setup -## PR TITLE FORMAT +## Testing +- [x] Documentation renders correctly +- [x] Links are valid +- [x] Follows documentation style guide" ``` -<type>: <description> (closes #<issue>) + +## PR Title Format + +Use clear, descriptive titles following conventional commit format: + +```text +<type>: Brief description of changes ``` -**Examples:** -- `feat: add user authentication (closes #42)` -- `fix: resolve database timeout (fixes #123)` -- `docs: update API documentation (closes #67)` +Examples: +- `feature: Add user profile page` +- `fix: Resolve database connection leak` +- `docs: Update API documentation` +- `refactor: Extract common auth logic` -## VERSION BUMPING RULES +## Common PR Checks -**MAJOR (X.0.0):** -- Breaking changes -- API removals -- Incompatible changes +Before creating PR, ensure: -**MINOR (0.X.0):** -- New features (backward compatible) -- New APIs -- Enhancements +- **All changes are committed** (clean working directory) +- Branch follows naming convention +- Commits follow conventional format +- All pre-commit hooks pass +- Tests are passing +- CHANGELOG.md updated (if user-facing change) +- No breaking changes without major version discussion -**PATCH (0.0.X):** -- Bug fixes -- Documentation -- Internal refactoring -- No new features +## After PR Creation -## CHANGELOG FORMAT +1. **Wait for CI checks** to complete +2. **Address review feedback** promptly +3. **Mark conversations as resolved** when fixed +4. **Rebase and update** if main branch changes +5. **Merge when approved** (maintainers handle merging) -**AI generates:** -```markdown -## [X.Y.Z] - YYYY-MM-DD +## Utility Commands -### Added -- New features +### Check Current Branch -### Changed -- Modifications +```bash +git branch --show-current +``` -### Fixed -- Bug fixes +### View Recent Commits + +```bash +git log --oneline -5 ``` -**NO [Unreleased] section** - version determined during PR creation. - -## ERROR RECOVERY - -**Uncommitted changes:** -→ `git status` to see files -→ Commit with `/git-commit` -→ Retry `/create-pr` - -**Rebase conflicts:** -→ Resolve conflicts in files -→ `git add` resolved files -→ `git rebase --continue` -→ Retry push - -**Push authentication failure:** -→ `gh auth setup-git` -→ `gh auth status` to verify -→ Retry push - -**PR creation failure:** -→ Check branch is pushed: `git branch -r | grep $BRANCH` -→ Verify gh CLI auth: `gh auth status` -→ Check for existing PR: `gh pr list` - -## EXECUTION CHECKLIST - -**Before PR creation:** -- [ ] Version bumped (if applicable) -- [ ] CHANGELOG updated -- [ ] All changes committed -- [ ] Working directory clean -- [ ] Branch rebased on latest main -- [ ] All tests passing -- [ ] Pre-commit hooks passed - -**During PR creation:** -- [ ] Branch pushed successfully -- [ ] PR title follows format -- [ ] PR body comprehensive -- [ ] Issue references included -- [ ] Version bump noted - -**After PR creation:** -- [ ] CI checks pass -- [ ] Review feedback addressed -- [ ] Mark ready for review -- [ ] After merge: run `/tag-and-release` +### Check if Branch is Behind + +```bash +git status +# Look for "Your branch is behind 'origin/main' by X commits" +``` + +### Interactive Rebase (Clean Up Commits) + +```bash +git rebase -i HEAD~3 # Last 3 commits +# Use 'squash' to combine, 'reword' to change messages +``` --- -**WORKFLOW:** version bump → create PR → merge → `/tag-and-release` creates git tag and release +**See [pr-template.md](./../pr-template.md) and [git-workflow.md](./../git-workflow.md) for detailed guidelines and examples.**