# hwdata Monthly Update Automation

This document describes the automated monthly update system for hwdata.

## Overview

The `monthly-update.py` script automates the complete monthly update workflow that was previously done manually. It handles everything from branch creation to PR submission.

## What It Does

The script performs these steps automatically:

1. **Creates feature branch** - e.g., `apr-update`, `may-update`
2. **Downloads ID files** - Runs `./configure && make download`
3. **Validates files** - Runs `make check` to ensure data integrity
4. **Analyzes changes** - Detects which files changed (pci, usb, vendor ids)
5. **Generates statistics** - Uses `compare-pci-ids.py` for detailed PCI changes
6. **Updates hwdata.spec**:
   - Bumps version number (e.g., 0.406 → 0.407)
   - Adds changelog entry with current date
   - Uses detected changes for changelog message
7. **Creates commit** - With proper message format reflecting actual changes
8. **Pushes and creates PR** - Using GitHub CLI with detailed description

## Prerequisites

Before running the script:

1. **Clean working tree** - Commit or stash any uncommitted changes
2. **On master branch** - Script warns if you're not (you can override)
3. **GitHub CLI installed** - `gh` command must be available and authenticated
4. **pnp.ids.csv downloaded** - Must be manually downloaded (see below)

### Installing GitHub CLI

```bash
# Fedora/RHEL
sudo dnf install gh

# Authenticate
gh auth login
```

### Downloading pnp.ids.csv

The UEFI PnP export is behind Cloudflare protection and can't be auto-downloaded:

1. Visit https://uefi.org/uefi-pnp-export in a browser
2. Complete any Cloudflare challenge
3. Save the file as `pnp.ids.csv` in the hwdata directory

The script will detect if this file is missing and provide instructions.

## Usage

### Basic Usage

```bash
# First, download pnp.ids.csv manually (see above)

# Then run the automation
./monthly-update.py
```

The script will:
- Create the branch
- Download and validate files
- Show you what changed
- Update hwdata.spec
- Create commit and PR
- Display the PR URL

### Testing: Local-Only Mode

To test the full workflow locally without pushing or creating a PR:

```bash
./monthly-update.py --local-only
```

This mode:
- Creates the branch
- Downloads and validates files  
- Updates hwdata.spec
- Creates commits
- **Stops before push/PR**
- Shows you how to undo the changes

Perfect for testing before running for real. To reset:
```bash
git checkout master
git branch -D apr-update
```

## What Happens After

Once the script completes:

1. **Review the PR** on GitHub - Check the automated description
2. **Wait for CI** - Packit builds and tests run automatically
3. **Sourcery AI review** - Reviews changes automatically
4. **Community feedback** - Wait ~24 hours for user feedback
5. **Merge the PR** - Manual merge via GitHub UI
6. **Tag and release** - Create tag with `make tag && git push --tags`
7. **GitHub release** - Create release via GitHub UI

## Commit Message Format

The script automatically generates commit messages based on what changed:

- Only pci.ids: `"Update pci"`
- Only USB: `"Update usb"`
- Only vendor files: `"Update vendor ids"`
- PCI + vendors: `"Update pci and vendor ids"`
- All files: `"Update pci, usb and vendor ids"`

All commits include: `Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>`

## PR Description Format

The script generates a detailed PR description with:

- Version number
- File update dates (from pci.ids and usb.ids headers)
- PCI statistics (vendors/devices added/removed/renamed)
- Testing checklist
- Automation attribution

Example:
```markdown
Automated monthly update of hardware IDs to version 0.407

## Updated Files
- PCI IDs: 2026-04-21
- USB IDs: 2025-12-13
- Vendor IDs (OUI/IAB/PNP): Updated

## PCI Changes
```
old vendor count: 2498
new vendor count: 2499
vendors added:    1
vendors removed:  0
vendors renamed:  0
devices added:    90
devices removed:  2
devices renamed:  14
```

## Testing
- [ ] `make check` passes
- [ ] Packit builds successful
- [ ] Tests pass on all targets

🤖 Generated by monthly-update.py automation
```

## Error Handling

The script handles common errors gracefully:

### Missing pnp.ids.csv
```
⚠️  pnp.ids.csv not found!
Please manually download from https://uefi.org/uefi-pnp-export
and save as pnp.ids.csv, then run this script again.
```

### Validation Failures
If `make check` fails, the script stops and shows the errors. Fix them manually and rerun.

### No Changes Detected
If no files changed (rare), the script warns you and asks if you want to continue.

### GitHub CLI Not Found
```
Error: 'gh' CLI not found. Install it from https://cli.github.com/
```

### Dirty Working Tree
```
Error: Working tree is not clean. Commit or stash changes first.
```

## Troubleshooting

### Branch Already Exists

If the monthly branch exists (e.g., from a previous attempt):
```
Branch apr-update already exists. Checking it out.
```
The script checks out the existing branch. Delete it manually if you want a fresh start:
```bash
git branch -D apr-update
```

### Script Interrupted

If you interrupt the script (Ctrl+C), it cleans up temporary files:
```
⚠️  Interrupted by user
```

### PR Creation Failed

If `gh pr create` fails (e.g., not authenticated):
```
Failed to create PR automatically. Create it manually on GitHub:
  Title: Monthly update - April 2026
  Body: ...
```

The commit is already pushed, so you can create the PR manually via GitHub web UI.

## Customization

You can modify the script for your workflow:

- **Commit message format** - Edit `create_commit()` function
- **PR description** - Edit `create_pr()` function
- **Version bump logic** - Edit `bump_version()` function
- **Branch naming** - Edit `get_month_name()` function

## Future Enhancements

Potential improvements:

1. **Scheduled GitHub Action** - Run script automatically on 1st of month
2. **Auto-merge** - Merge PR automatically after 24h + CI green
3. **Auto-tag** - Create git tag automatically after PR merge
4. **Slack notifications** - Notify maintainer when PR is ready
5. **pnp.ids.csv auto-retry** - Try different methods to bypass Cloudflare

## Manual Override

If the automation doesn't work or you prefer manual control, follow the manual workflow documented in CLAUDE.md under "Manual Release Process".

## Support

For issues with the script:
- Check CLAUDE.md for manual workflow
- Review error messages carefully
- Ensure all prerequisites are met
- File issues at https://github.com/vcrhonek/hwdata/issues
