nip/docs/automatic-updates.md

# Automatic Updates Guide

## Overview

NIP's automatic update system keeps your recipes, build tools, and NIP itself up to date with minimal user intervention. Updates are checked periodically and can be applied with a single command.

## Features

- **Automatic Update Checking**: Periodic checks for new versions
- **Multiple Update Channels**: Stable, Beta, and Nightly
- **Configurable Frequency**: Never, Daily, Weekly, or Monthly
- **Selective Notifications**: Choose which components to monitor
- **Automatic Backups**: All updates create backups before applying
- **Easy Rollback**: Revert to previous versions if needed
- **Non-Intrusive**: Updates never interrupt your workflow

## Quick Start

### 1. Check for Updates

```bash
nip update check
```

Output:
```
🔍 Checking for updates...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📦 Update Available: recipes
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Current Version: abc1234
Latest Version:  def5678

Changelog:
- Added 50 new recipes
- Updated Nix recipes for 24.05
- Fixed Gentoo build issues

To update, run:
  nip update recipes
```

### 2. Update Components

```bash
# Update recipes
nip update recipes

# Update all components
nip update all

# Update NIP itself
nip update self
```

### 3. Configure Automatic Updates

```bash
# Enable automatic updates
nip update config --enable --frequency weekly

# Set update channel
nip update config --channel stable
```

## Configuration

### Update Configuration File

Settings are stored in `~/.config/nip/update-config.json`:

```json
{
  "enabled": true,
  "channel": "stable",
  "frequency": "weekly",
  "lastCheck": 1700000000,
  "notifyRecipes": true,
  "notifyTools": true,
  "notifyNip": true
}
```

### Configuration Options

| Option | Description | Values | Default |
|--------|-------------|--------|---------|
| `enabled` | Enable automatic updates | true/false | true |
| `channel` | Update channel | stable/beta/nightly | stable |
| `frequency` | Check frequency | never/daily/weekly/monthly | weekly |
| `notifyRecipes` | Notify of recipe updates | true/false | true |
| `notifyTools` | Notify of tool updates | true/false | true |
| `notifyNip` | Notify of NIP updates | true/false | true |

### Update Channels

**Stable** (Recommended)
- Thoroughly tested releases
- Recommended for production use
- Updates every 2-4 weeks
- Maximum stability

**Beta**
- Early access to new features
- Tested but may have minor issues
- Updates weekly
- Good for testing new features

**Nightly**
- Bleeding edge development builds
- May have bugs or breaking changes
- Updates daily
- For developers and early adopters

### Update Frequency

**Never**
- Manual updates only
- No automatic checking
- Use when you want full control

**Daily**
- Check for updates every day
- Good for nightly channel users
- Ensures latest features/fixes

**Weekly** (Recommended)
- Check for updates once per week
- Good balance of freshness and stability
- Recommended for most users

**Monthly**
- Check for updates once per month
- Minimal interruption
- Good for stable environments

## Usage

### Check for Updates

```bash
# Check if updates are available
nip update check

# Force check even if not due
nip update check --force
```

### Update Recipes

Recipes contain package definitions and build instructions:

```bash
# Update recipe repository
nip update recipes
```

Output:
```
📥 Fetching recipe updates...
🔄 Updating recipes...

📝 Changes:
abc1234 Added vim recipe
def5678 Updated firefox to 120.0
ghi9012 Fixed gentoo portage issues

✅ Recipes updated successfully
```

### Update Tools

Build tools (Nix, Gentoo, PKGSRC) are updated via recipes:

```bash
# Tools are updated through recipes
nip update recipes
```

### Update NIP

Update NIP itself to the latest version:

```bash
# Check for NIP updates
nip update check

# Update NIP
nip update self
```

Output:
```
📦 NIP Update Available

Current Version: 0.1.0
Latest Version:  0.2.0

Changelog:
- Added remote binary cache
- Improved container support
- Performance improvements

Update now? (y/N): y

📥 Downloading NIP update...
🔄 Installing update...
✅ NIP updated successfully
   Please restart NIP to use the new version
```

### Update All Components

Update everything at once:

```bash
nip update all
```

Output:
```
🔄 Updating all components...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📦 Updating Recipes
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Recipes updated successfully

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📦 Updating NIP
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ NIP updated successfully

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ All updates completed successfully
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

## Configuration Commands

### Enable/Disable Updates

```bash
# Enable automatic updates
nip update config --enable

# Disable automatic updates
nip update config --disable
```

### Set Update Channel

```bash
# Use stable channel (recommended)
nip update config --channel stable

# Use beta channel
nip update config --channel beta

# Use nightly channel
nip update config --channel nightly
```

### Set Update Frequency

```bash
# Check weekly (recommended)
nip update config --frequency weekly

# Check daily
nip update config --frequency daily

# Check monthly
nip update config --frequency monthly

# Never check automatically
nip update config --frequency never
```

### Configure Notifications

```bash
# Enable recipe notifications
nip update config --notify-recipes yes

# Disable tool notifications
nip update config --notify-tools no

# Enable NIP notifications
nip update config --notify-nip yes
```

### View Configuration

```bash
nip update status
```

Output:
```
Update Configuration
====================

Enabled: Yes
Channel: stable
Frequency: weekly
Last Check: 2024-11-15 10:30:00

Notifications:
  Recipes: Yes
  Tools: Yes
  NIP: Yes

🔍 Checking for updates...
✅ All components are up to date
```

## Backup and Rollback

### Automatic Backups

All updates automatically create backups before applying changes:

```
~/.cache/nip/backups/
├── recipes-20241115-103000/
├── nip-20241115-103100.bin
└── gentoo-20241110-150000/
```

### List Backups

```bash
nip update backups
```

Output:
```
Available Backups:
==================

  recipes-20241115-103000
    Date: 2024-11-15 10:30:00
    Path: /home/user/.cache/nip/backups/recipes-20241115-103000

  nip-20241115-103100.bin
    Date: 2024-11-15 10:31:00
    Path: /home/user/.cache/nip/backups/nip-20241115-103100.bin

Total: 2 backups
```

### Rollback to Previous Version

```bash
# Rollback recipes
nip update rollback recipes

# Rollback NIP
nip update rollback nip
```

Output:
```
🔄 Rolling back recipes to backup from 2024-11-15 10:30:00
✅ Rollback successful
```

### Clean Old Backups

```bash
# Clean backups older than 30 days (default)
nip update clean-backups

# Keep only last 7 days
nip update clean-backups --keep-days 7
```

## Integration with Workflows

### Daily Development Workflow

```bash
# Morning routine
nip update check

# If updates available
nip update all

# Continue working
nip build myproject
```

### CI/CD Integration

```yaml
# GitHub Actions
name: Build with Latest Recipes

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install NIP
        run: curl -sSL https://nip.example.com/install.sh | sh

      - name: Update Recipes
        run: nip update recipes

      - name: Build Package
        run: nip build myapp
```

### Automated Update Script

```bash
#!/bin/bash
# update-nip.sh - Automated update script

# Check for updates
nip update check --force

# Update all components
nip update all

# Verify installation
nip --version

# Run tests
nip build --test myproject
```

## Update Notifications

### Non-Intrusive Notifications

Updates are checked in the background and notifications are shown at appropriate times:

```bash
$ nip build firefox

📦 Update Available: recipes (run 'nip update check' for details)

🔨 Building firefox...
```

### Disable Notifications

```bash
# Disable all notifications
nip update config --notify-recipes no --notify-tools no --notify-nip no

# Or disable updates entirely
nip update config --disable
```

## Troubleshooting

### Update Check Fails

```bash
❌ Failed to check for updates: connection timeout
```

**Solutions:**
1. Check internet connectivity
2. Verify firewall allows HTTPS
3. Try again later
4. Use `--force` to retry immediately

### Update Fails

```bash
❌ Failed to update recipes: merge conflict
```

**Solutions:**
1. Rollback to previous version: `nip update rollback recipes`
2. Clean and re-clone: `rm -rf ~/.local/share/nip/recipes && nip update recipes`
3. Check for local modifications

### Backup Fails

```bash
⚠️  Failed to create backup: disk full
```

**Solutions:**
1. Free up disk space
2. Clean old backups: `nip update clean-backups`
3. Disable backups (not recommended): Edit config manually

### Rollback Fails

```bash
❌ No backup found for: recipes
```

**Solutions:**
1. List available backups: `nip update backups`
2. Manually restore from backup directory
3. Re-install component from scratch

## Best Practices

### For Individual Users

1. **Enable automatic updates** with weekly frequency
2. **Use stable channel** for production work
3. **Check updates** before starting important work
4. **Keep backups** for at least 30 days
5. **Test updates** in non-critical projects first

### For Teams

1. **Coordinate updates** across team members
2. **Use same update channel** for consistency
3. **Document update schedule** in team wiki
4. **Test updates** in staging environment first
5. **Keep update logs** for troubleshooting

### For CI/CD

1. **Update recipes** at start of pipeline
2. **Pin specific versions** for reproducibility
3. **Cache updated recipes** between runs
4. **Monitor update failures** in CI logs
5. **Rollback automatically** on build failures

## Advanced Configuration

### Custom Update Server

Edit `~/.config/nip/update-config.json`:

```json
{
  "updateUrl": "https://custom-updates.example.com/v1",
  "enabled": true,
  "channel": "stable"
}
```

### Update Hooks

Run custom scripts after updates:

```bash
# ~/.config/nip/hooks/post-update.sh
#!/bin/bash

echo "Update completed at $(date)"

# Rebuild critical packages
nip build --rebuild myapp

# Send notification
notify-send "NIP Updated" "Recipes and tools updated successfully"
```

### Selective Component Updates

Update only specific components:

```bash
# Update only recipes, skip NIP
nip update config --notify-nip no
nip update recipes

# Update only NIP, skip recipes
nip update config --notify-recipes no
nip update self
```

## Security Considerations

### Update Verification

- All updates are verified with checksums
- HTTPS is used for all downloads
- Backups are created before applying updates
- Rollback is available if issues occur

### Update Sources

- Official updates come from trusted servers
- Custom update servers can be configured
- Updates are signed (future feature)
- Verify update authenticity before applying

### Permissions

- Updates don't require root access
- User-level installations only
- No system-wide modifications
- Isolated from system packages

## FAQ

**Q: How often should I update?**
A: Weekly is recommended for most users. Daily for nightly channel, monthly for stable environments.

**Q: Will updates break my builds?**
A: Stable channel updates are thoroughly tested. Backups allow easy rollback if issues occur.

**Q: Can I skip an update?**
A: Yes, updates are never forced. You can skip any update and apply it later.

**Q: How much disk space do backups use?**
A: Typically 100-500MB per backup. Clean old backups regularly to save space.

**Q: Can I update offline?**
A: No, updates require internet connectivity. Download updates on another machine and transfer manually if needed.

**Q: What happens if an update fails?**
A: The system automatically rolls back to the previous version using the backup.

**Q: Can I test updates before applying?**
A: Yes, use beta or nightly channels in a test environment before updating production.

**Q: How do I know what changed in an update?**
A: Changelogs are shown before applying updates. Check `nip update check` for details.

## See Also

- [Binary Cache Guide](binary-cache.md) - Caching system
- [Remote Cache Guide](remote-cache.md) - Team collaboration
- [Configuration Guide](configuration.md) - NIP configuration
- [Build System Guide](source-build-guide.md) - Building packages