# OpenRewrite Update Process Documentation

## Overview

This document describes the automated dependency update process for CFTunnels using OpenRewrite with monthly execution and manual review workflow.

## Process Flow

### 1. Monthly Schedule
- **Frequency**: Monthly on the 1st at 2 AM UTC
- **Trigger**: Scheduled Gitea workflow
- **Manual Trigger**: Available via `workflow_dispatch` for urgent security updates

### 2. Safety Validation Steps

#### Pre-Update Checks
1. **Environment Validation**
   - Check Java 17 toolchain
   - Verify Gradle wrapper integrity
   - Confirm access to required repositories

2. **Test Suite Execution**
   - Full unit test suite
   - Full integration test suite
   - Performance baseline tests

3. **Configuration Validation**
   - Application properties integrity
   - Environment variable presence
   - Database connectivity

#### OpenRewrite Execution
1. **Dry Run Mode**
   - Preview all proposed changes
   - Generate change report
   - Verify no breaking changes

2. **Apply Updates**
   - Safe dependency updates only
   - Spring Boot minor versions (3.4.x → 3.5.x)
   - Security patches for Spring ecosystem

#### Post-Update Validation
1. **Test Suite Re-execution**
   - All tests must pass
   - Performance regression checks
   - Integration test validation

2. **Safety Script Execution**
   - Comprehensive compatibility checks
   - Breaking change detection
   - Safety report generation

### 3. Pull Request Creation

#### PR Target
- **Target Branch**: `origin/test`
- **Source Branch**: `dependency-updates-YYYY-MM`
- **Review Required**: Manual review mandatory

#### PR Content
- **Title**: "Monthly dependency updates via OpenRewrite - YYYY-MM"
- **Description**: 
  - Summary of changes applied
  - Test results before and after
  - Safety validation reports
  - Updated dependencies list

#### Labels
- `dependencies`
- `openrewrite`  
- `monthly-update`
- `needs-review`

### 4. Manual Review Process

#### Review Checklist
- [ ] Dependency versions are compatible
- [ ] No breaking changes introduced
- [ ] Test results are green
- [ ] Safety reports are clean
- [ ] Configuration files remain intact

#### Approval Workflow
1. **Technical Review**: Verify dependency compatibility
2. **Security Review**: Confirm no vulnerabilities introduced
3. **Operations Review**: Validate deployment readiness

#### Merge Decision
- **Auto-merge**: Disabled - always requires manual approval
- **Conflict Resolution**: Manual intervention required
- **Rollback**: Available via rollback request template

## Dependency Update Rules

### Safe Updates (Automatic)
- ✅ Spring Boot minor versions (3.4.x → 3.5.x)
- ✅ SpringDoc OpenAPI compatible versions
- ✅ PostgreSQL driver updates (42.x series)
- ✅ Spring ecosystem security patches
- ✅ Hibernate validator updates

### Excluded Updates (Manual Review Required)
- ❌ Spring Boot major versions (4.x)
- ❌ Jakarta EE namespace changes
- ❌ Experimental Spring features
- ❌ Database schema migrations
- ❌ OAuth2 provider configuration changes

### Protected Configurations
- 🔒 Cloudflare API integration
- 🔒 Database connection settings
- 🔒 OAuth2 provider endpoints
- 🔒 Custom security configurations
- 🔒 Docker deployment configurations

## Rollback Procedures

### Emergency Rollback
1. **Create Rollback Request**
   - Use `.github/ISSUE_TEMPLATE/rollback-request.md`
   - Specify target version
   - Assess impact severity

2. **Rollback Execution**
   - Create rollback branch
   - Revert dependency changes
   - Update Docker images
   - Deploy rollback version

3. **Post-Rollback Validation**
   - Verify functionality restored
   - Run full test suite
   - Monitor production metrics

### Manual Override
- Disable automatic updates:
  ```bash
  # In build.gradle, pin versions
  dependencies {
      implementation 'org.springframework.boot:spring-boot-starter:3.4.5'
      // ... other pinned dependencies
  }
  ```

- Skip monthly update:
  ```bash
  git checkout test
  # Create commit to skip update
  echo "SKIP_UPDATE=true" > .skip-openrewrite
  git add .skip-openrewrite
  git commit -m "Skip OpenRewrite update this month"
  ```

## Monitoring and Alerting

### Pre-Update Notifications
- **Timing**: 3 days before monthly execution
- **Channel**: Gitea notifications
- **Content**: Preview of planned updates

### Post-Update Notifications
- **Timing**: Immediately after PR creation
- **Channel**: Gitea PR notifications
- **Content**: PR link with test results

### Failure Notifications
- **Timing**: Immediately on failure
- **Channel**: Gitea issue creation
- **Content**: Error details and rollback instructions

## Configuration Files

### OpenRewrite Configuration
- **File**: `rewrite.yml`
- **Recipes**: Safe dependency updates only
- **Exclusions**: Experimental features, breaking changes

### CI/CD Configuration  
- **File**: `.gitea/workflows/rewrite-updates.yml`
- **Schedule**: Monthly cron trigger
- **Safety**: Full test suite before/after updates

### Safety Script
- **File**: `scripts/rewrite-safety-check.sh`
- **Purpose**: Additional validation checks
- **Execution**: Pre and post-update validation

## Success Metrics

### Automated Metrics
- Number of successful monthly updates
- Time from update to merge
- Test pass rate percentage
- Rollback frequency

### Manual Metrics
- Review time duration
- Manual intervention frequency
- Configuration adjustments needed
- Security update effectiveness

## Troubleshooting

### Common Issues

#### Build Failures
```bash
# Check for compilation errors
./gradlew compileJava

# Review dependency conflicts
./gradlew dependencies

# Check for version conflicts
./gradlew dependencyInsight --dependency spring-boot-starter
```

#### Test Failures
```bash
# Run specific failing test
./gradlew test --tests "com.example.FailingTest"

# Run with debug output
./gradlew test --debug

# Check test reports
open build/reports/tests/test/index.html
```

#### Integration Test Issues
```bash
# Run integration tests only
./gradlew integrationTestOnly

# Check test database setup
# Review application-test.properties
```

### Getting Help

1. **Rollback Request**: Use rollback issue template
2. **Configuration Review**: Create issue with `configuration` label
3. **Test Failures**: Create issue with `tests` label and include test reports
4. **Urgent Issues**: Mention `@mentions` in issue for immediate attention

## Maintenance

### Monthly Tasks
- Review update success rate
- Update OpenRewrite recipes if needed
- Review safety script effectiveness
- Update documentation based on learnings

### Quarterly Tasks
- Review dependency update strategy
- Update safety exclusion rules
- Review rollback procedures effectiveness
- Update monitoring and alerting configurations

### Annual Tasks
- Major version migration planning
- OpenRewrite recipe updates
- Security audit of update process
- Process optimization review

## Contact and Support

### Process Questions
- Create issue with `process` label
- Tag relevant team members
- Provide context and expected outcomes

### Technical Issues  
- Create issue with `technical` label
- Include error logs and stack traces
- Specify environment and version details

### Security Concerns
- Create issue with `security` label
- Mark as confidential if needed
- Contact security team directly for urgent matters

---

*This document is maintained by the CFTunnels team. Last updated: $(date +%Y-%m-%d)*