# Upgrade Guide

**Status**: ✅ Complete

**Last Updated**: December 5, 2025

---

## Overview

This guide helps you upgrade RiceCoder to a newer version while preserving your configuration, sessions, and data.

## Table of Contents

- [Before Upgrading](#before-upgrading)
- [Upgrade Methods](#upgrade-methods)
- [Post-Upgrade Steps](#post-upgrade-steps)
- [Troubleshooting](#troubleshooting)
- [Downgrading](#downgrading)
- [Version History](#version-history)

---

## Before Upgrading

### Check Current Version

```bash
rice --version
```

### Backup Your Data

Before upgrading, backup your important data:

```bash
# Backup configuration
cp -r ~/.ricecoder ~/.ricecoder.backup

# Backup project configuration
cp -r .agent .agent.backup
```

### Check Release Notes

Review the release notes for the version you're upgrading to:

- [Release Notes](./Alpha-Release-Notes-v0.1.3.md)
- [GitHub Releases](https://github.com/moabualruz/ricecoder/releases)

### Check Breaking Changes

Some versions may have breaking changes. Check:

1. **Configuration Changes**: New or changed configuration options
2. **API Changes**: Changes to CLI commands or APIs
3. **Data Format Changes**: Changes to session or configuration formats
4. **Dependency Updates**: Updates to dependencies

---

## Upgrade Methods

### Method 1: Using Cargo (Recommended)

```bash
# Update to latest version
cargo install ricecoder --force

# Verify upgrade
rice --version
```

### Method 2: From Source

```bash
# Clone the latest version
git clone https://github.com/moabualruz/ricecoder.git
cd ricecoder

# Build and install
cargo install --path projects/ricecoder --force

# Verify upgrade
rice --version
```

### Method 3: Pre-built Binaries

When available, download pre-built binaries:

1. Visit [GitHub Releases](https://github.com/moabualruz/ricecoder/releases)
2. Download the binary for your platform
3. Extract and install
4. Verify installation: `rice --version`

---

## Post-Upgrade Steps

### 1. Verify Installation

```bash
# Check version
rice --version

# Check configuration
rice config show

# Test basic functionality
rice chat --help
```

### 2. Migrate Configuration (if needed)

Some upgrades may require configuration migration:

```bash
# Validate configuration
rice config validate

# If validation fails, check release notes for migration steps
```

### 3. Update Configuration

If there are new configuration options, update your configuration:

```bash
# Show current configuration
rice config show

# Update specific settings
rice config set new-option value

# Or edit configuration file directly
nano ~/.ricecoder/config.yaml
```

### 4. Test Features

Test key features to ensure everything works:

```bash
# Test chat
rice chat

# Test code generation
rice gen --spec test-feature --preview

# Test LSP
rice lsp status

# Test completion
rice completion status
```

### 5. Update Project Configuration (if needed)

If you have project-specific configuration, update it:

```bash
# Check project configuration
cat .agent/config.yaml

# Update if needed
rice config set --project new-option value
```

---

## Troubleshooting

### Issue: Upgrade Fails

**Problem**: Cargo fails to install the new version.

**Solution**:

1. Clear cargo cache:
   ```bash
   cargo clean
   ```

2. Try installing again:
   ```bash
   cargo install ricecoder --force
   ```

3. If still failing, try from source:
   ```bash
   git clone https://github.com/moabualruz/ricecoder.git
   cd ricecoder
   cargo install --path projects/ricecoder --force
   ```

### Issue: Configuration Not Working After Upgrade

**Problem**: Configuration settings are not recognized after upgrade.

**Solution**:

1. Validate configuration:
   ```bash
   rice config validate
   ```

2. Check for breaking changes in release notes

3. Reset to defaults and reconfigure:
   ```bash
   rice config reset
   rice config set provider openai
   rice config set model gpt-4
   ```

4. Check configuration file for syntax errors:
   ```bash
   cat ~/.ricecoder/config.yaml
   ```

### Issue: Sessions Not Loading After Upgrade

**Problem**: Saved sessions don't load after upgrade.

**Solution**:

1. Check session directory:
   ```bash
   ls -la ~/.ricecoder/sessions/
   ```

2. Check session file format:
   ```bash
   cat ~/.ricecoder/sessions/my-session.json
   ```

3. If format changed, sessions may need migration (check release notes)

4. Try creating a new session:
   ```bash
   rice session save new-session
   ```

### Issue: Performance Issues After Upgrade

**Problem**: RiceCoder is slower after upgrade.

**Solution**:

1. Clear cache:
   ```bash
   rice cache clear
   ```

2. Check system resources:
   ```bash
   top  # macOS/Linux
   # or Task Manager (Windows)
   ```

3. Restart RiceCoder

4. Check release notes for performance-related changes

5. If issue persists, downgrade and report the issue

---

## Downgrading

If you need to downgrade to a previous version:

### Downgrade Using Cargo

```bash
# Install specific version
cargo install ricecoder --version 0.1.6 --force

# Verify downgrade
rice --version
```

### Restore from Backup

If you backed up your data before upgrading:

```bash
# Restore configuration
rm -rf ~/.ricecoder
cp -r ~/.ricecoder.backup ~/.ricecoder

# Restore project configuration
rm -rf .agent
cp -r .agent.backup .agent
```

### Report Issues

If you need to downgrade due to issues, please report the issue:

1. [GitHub Issues](https://github.com/moabualruz/ricecoder/issues)
2. [GitHub Discussions](https://github.com/moabualruz/ricecoder/discussions)
3. [Discord](https://discord.gg/your-invite-code)

---

## Version History

### v0.1.6 (Current - Alpha)

**Release Date**: December 6, 2025

**New Features**:
- Multi-Project Orchestration
- Domain-Specific Agents
- Learning System with personalization

**Breaking Changes**: None

**Migration Steps**: None required

**Upgrade Path**: From v0.1.5 → v0.1.6

---

### v0.1.5 (Previous - Alpha)

**Release Date**: December 3, 2025

**Features**:
- Code Generation from specs
- Multi-Agent Framework
- Workflows and Execution Plans
- Sessions and Modes

**Upgrade Path**: From v0.1.1 → v0.1.2

---

### v0.1.1 (Alpha)

**Release Date**: December 1, 2025

**Features**:
- CLI Foundation
- AI Providers (75+)
- TUI Interface
- Spec System
- File Management
- Templates and Boilerplates
- Research System
- Permissions System
- Custom Commands
- Local Models (Ollama)
- Storage and Configuration

---

## Upgrade Checklist

Before upgrading, ensure you:

- [ ] Check current version: `rice --version`
- [ ] Backup configuration: `cp -r ~/.ricecoder ~/.ricecoder.backup`
- [ ] Backup project config: `cp -r .agent .agent.backup`
- [ ] Review release notes
- [ ] Check for breaking changes
- [ ] Have internet connection (for downloading)
- [ ] Have sufficient disk space

After upgrading, ensure you:

- [ ] Verify installation: `rice --version`
- [ ] Validate configuration: `rice config validate`
- [ ] Test basic functionality: `rice chat --help`
- [ ] Update configuration if needed
- [ ] Test key features
- [ ] Update project configuration if needed
- [ ] Delete backup if everything works

---

## Getting Help

If you encounter issues during upgrade:

1. **Check Troubleshooting**: See [Troubleshooting](#troubleshooting) above
2. **Check Release Notes**: Review release notes for your version
3. **Check FAQ**: [FAQ](./FAQ.md)
4. **Ask Community**: [GitHub Discussions](https://github.com/moabualruz/ricecoder/discussions)
5. **Report Issue**: [GitHub Issues](https://github.com/moabualruz/ricecoder/issues)

---

## See Also

- [Installation & Setup](./Installation-Setup.md) - Installation guide
- [Configuration Guide](./Configuration.md) - Configuration options
- [Backup & Recovery Guide](./Backup-Recovery-Guide.md) - Backup and recovery
- [Troubleshooting Guide](./Troubleshooting.md) - Troubleshooting help
- [Release Notes](./Alpha-Release-Notes-v0.1.3.md) - Latest release notes

---

*Last updated: December 5, 2025*