branchyard/RELEASE_v1.3.0.md

branchyard — Your shipyard for parallel development workflows. Maintain your digital yard with clean branches, productive workflows, and AI-era readiness.

# Release v1.3.0 - Major Architecture Change 🏗️

## ⚠️ BREAKING CHANGE

**Worktrees are now created within the project directory instead of the parent directory.**

### Migration Required

**Before v1.3.0:**
```
/parent-directory/
├── your-project/
├── worktree-1/     ❌ Outside project
└── worktree-2/     ❌ Outside project
```

**After v1.3.0:**
```
/your-project/
├── .worktrees/
│   ├── worktree-1/  ✅ Inside project
│   └── worktree-2/  ✅ Inside project
└── parallel-dev.code-workspace
```

### How to Migrate

1. Remove existing worktrees using v1.2.x or `git worktree remove`
2. Update to v1.3.0
3. Recreate your worktrees - they'll now be in `.worktrees/`

## 🎯 Why This Change?

The previous design had significant issues:
- **Directory pollution**: Cluttered parent directories with worktrees
- **Permission issues**: Might not have write access to parent directory
- **Poor portability**: Couldn't easily move/archive complete projects
- **Cleanup problems**: `rm -rf project/` didn't remove everything
- **No gitignore**: Couldn't exclude worktrees since they were outside the project

## ✨ New Features

### 1. Contained Worktrees
- Worktrees now created in `.worktrees/` subdirectory within your project
- Keeps everything self-contained and organized
- Add `.worktrees/` to your `.gitignore` to exclude from version control

### 2. Interactive Workspace Opening
- **New prompt**: "Open workspace in editor now? (Y/n):" after creation
- Defaults to Yes for immediate productivity
- Shows clear instructions if you choose not to open

### 3. Better User Guidance
- Shows what files were created and where
- Provides command to open workspace later if needed
- Clear summary at completion with all important paths

### 4. Session Overwrite Protection
- Warns when saving over an existing session name
- Must explicitly confirm to overwrite
- Shows "updated" vs "saved" for clarity

### 5. Migration Warnings
- Detects worktrees in old location (`../worktree-name`)
- Warns user about the change
- Asks for confirmation before proceeding

## 🔧 Improvements

### Enhanced User Experience
- **Workspace feedback**: "📝 Created workspace file: parallel-dev.code-workspace"
- **Opening feedback**: "🚀 Opening workspace in cursor..."
- **Completion summary**: Shows worktree location and workspace file
- **Next steps**: Clear instructions on how to open workspace manually

### Better Session Management
- Session overwrite warnings prevent accidental data loss
- Clear feedback when updating vs creating new sessions
- Sessions persist after worktree removal (by design for re-creation)

### Improved Workspace Generation
- Automatically updates workspace paths from old to new format
- Detects and reports when updating old workspace files
- Proper path resolution for contained worktrees

## 📚 Usage Examples

### Create worktrees (now in .worktrees/)
```bash
branchyard feature-x bugfix-y
# Creates:
#   .worktrees/feature-x/
#   .worktrees/bugfix-y/
#   parallel-dev.code-workspace
```

### Interactive workspace opening
```
📝 Created workspace file: parallel-dev.code-workspace
Open workspace in editor now? (Y/n): y
🚀 Opening workspace in cursor...
```

### Session management with overwrite protection
```
Do you want to save this setup as a named session? (y/n): y
Enter session name: my-work
⚠️  Session 'my-work' already exists. Overwrite? (y/n): y
💾 Session 'my-work' updated.
```

## 🔄 Upgrade Instructions

```bash
# 1. Remove old worktrees (if any)
branchyard remove --delete-branch  # on v1.2.x

# 2. Update branchyard
bun update -g branchyard

# 3. Create new worktrees in the new location
branchyard feature-x bugfix-y
```

## 📝 Notes

- The `.worktrees/` directory is created automatically
- Add `.worktrees/` to your `.gitignore` file
- Old worktrees must be manually removed
- Sessions are not automatically deleted when removing worktrees

## Compatibility

- Requires Bun v1.0 or higher
- Tested with Bun v1.2.19
- Works with VS Code, Cursor, Windsurf, and other editors

## Contributors

- Sivaram P (@SivaramPg)

---

*Your shipyard for parallel development workflows* ⚓

**This is a breaking change that significantly improves the architecture of branchyard. The new contained approach is the correct design for a project-scoped tool.**