# Renovate Configuration Guide

## Overview

This template uses [Renovate](https://renovatebot.com) for automated dependency management. Renovate provides more features and flexibility compared to Dependabot, including better uv support and more granular control over update strategies.

## Configuration

The Renovate configuration is located at `.github/renovate.json`:

```json
{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": [
    "config:recommended",
    ":dependencyDashboard"
  ],
  "baseBranches": ["main"],
  "labels": ["dependencies"],
  "automerge": true,
  "automergeType": "pr",
  "platformAutomerge": true,
  "uv": {
    "enabled": true
  },
  "packageRules": [
    {
      "description": "Auto-merge non-major updates",
      "matchUpdateTypes": ["patch", "minor", "pin", "digest"],
      "automerge": true,
      "platformAutomerge": true
    },
    {
      "description": "Major updates need review",
      "matchUpdateTypes": ["major"],
      "automerge": false
    },
    {
      "description": "Group by uv dependency groups",
      "matchManagers": ["uv"],
      "groupByDepType": true
    },
    {
      "description": "Security group never auto-merges",
      "matchManagers": ["uv"],
      "matchDepGroups": ["security"],
      "automerge": false
    }
  ],
  "prConcurrentLimit": 3,
  "prCreation": "immediate",
  "rebaseWhen": "auto"
}
```

## Key Features

### 1. Dependency Dashboard
- Renovate creates an issue called "Dependency Dashboard"
- Central view of all pending updates
- Ability to trigger specific updates manually
- Shows update confidence scores

### 2. Auto-merge Strategy
- **Patch and Minor**: Auto-merge when all checks pass
- **Major**: Require manual review
- **Security**: Always require manual review (even patches)

### 3. uv Support
- Full understanding of uv.lock files
- Respects uv version constraints
- Groups updates by dependency groups (main, dev, security, etc.)

### 4. PR Management
- Maximum 3 concurrent PRs to avoid noise
- Automatic rebasing when base branch changes
- Clear PR descriptions with release notes

## Enabling Renovate

### Option 1: GitHub App (Recommended)
1. Install the [Renovate GitHub App](https://github.com/apps/renovate)
2. Grant access to your repository
3. Renovate will automatically detect the config file

### Option 2: Self-Hosted
For enterprise environments, you can run Renovate yourself:
```bash
# Using Docker
docker run --rm renovate/renovate
```

## Customization

### Changing Update Schedule
Add to `renovate.json`:
```json
{
  "schedule": ["after 10pm every weekday", "before 5am every weekday"]
}
```

### Grouping Updates
Group all patch updates into a single PR:
```json
{
  "packageRules": [{
    "matchUpdateTypes": ["patch"],
    "groupName": "patch updates",
    "groupSlug": "patch"
  }]
}
```

### Excluding Packages
```json
{
  "ignoreDeps": ["package-to-ignore"]
}
```

## Comparison with Dependabot

| Feature | Renovate | Dependabot |
|---------|----------|------------|
| uv.lock support | ✅ Full | ⚠️ Limited |
| Update grouping | ✅ Flexible | ⚠️ Basic |
| Release notes | ✅ Detailed | ✅ Good |
| Auto-merge | ✅ Built-in | 🔧 Workflow needed |
| Scheduling | ✅ Flexible | ✅ Basic |
| Self-hosting | ✅ Yes | ❌ No |
| Configuration | ✅ JSON/JS | ✅ YAML |

## Troubleshooting

### PRs Not Being Created
1. Check the Dependency Dashboard issue for errors
2. Verify Renovate has repository access
3. Check branch protection rules allow Renovate

### Auto-merge Not Working
1. Ensure `"Allow auto-merge"` is enabled in repository settings
2. Verify all required status checks are passing
3. Check that the merge strategy in `.env` matches repository settings

### Too Many PRs
Adjust `prConcurrentLimit` in the configuration:
```json
{
  "prConcurrentLimit": 1  // Only one PR at a time
}
```

## Best Practices

1. **Review Security Updates**: Never auto-merge security updates
2. **Test Coverage**: Ensure good test coverage before enabling auto-merge
3. **Gradual Rollout**: Start conservative, then increase automation
4. **Monitor Dashboard**: Check the Dependency Dashboard weekly
5. **Update Confidence**: Renovate shows confidence scores - use them!

## Resources

- [Renovate Documentation](https://docs.renovatebot.com/)
- [Configuration Options](https://docs.renovatebot.com/configuration-options/)
- [Self-Hosting Guide](https://docs.renovatebot.com/self-hosting/)
- [Presets](https://docs.renovatebot.com/presets/)
