Initial commit

2025-11-29 18:25:55 +08:00
commit d8b4535ddb
15 changed files with 4992 additions and 0 deletions
--- a/commands/rust-upgrade-edition.md
+++ b/commands/rust-upgrade-edition.md
@@ -0,0 +1,347 @@
+---
+description: Upgrade Rust project to Rust 2024 Edition
+---
+
+You are helping upgrade a Rust project to Rust 2024 Edition.
+
+## Your Task
+
+Guide the user through upgrading their project from an older edition (2015, 2018, or 2021) to Rust 2024 Edition, handling breaking changes and migration steps.
+
+## Steps
+
+1. **Check Current Status**
+
+   Read Cargo.toml to determine:
+   - Current edition
+   - Current rust-version (MSRV) if set
+   - Project structure (workspace or single crate)
+
+   ```rust
+   Current Status:
+   - Edition: 2021
+   - MSRV: Not set
+   - Type: Single crate
+   ```
+
+2. **Verify Rust Version**
+
+   Check that Rust toolchain is recent enough:
+
+   ```bash
+   rustc --version
+   ```
+
+   Required: Rust 1.85.0 or later for full Rust 2024 support.
+
+   If version is too old:
+   ```
+   ⚠️ Rust version is too old. Rust 2024 Edition requires 1.85.0 or later.
+
+   Please update:
+   ```bash
+   rustup update stable
+   ```
+   ```
+
+3. **Create Backup**
+
+   Suggest creating a git commit or backup:
+   ```
+   💡 Recommendation: Commit current changes before upgrading
+
+   ```bash
+   git add .
+   git commit -m "Pre-2024 edition upgrade snapshot"
+   ```
+   ```
+
+4. **Update Cargo.toml**
+
+   For single crate:
+   ```toml
+   [package]
+   name = "my-project"
+   version = "0.1.0"
+   edition = "2024"  # Updated from 2021
+   rust-version = "1.85"  # Add MSRV
+   ```
+
+   For workspace:
+   ```toml
+   [workspace]
+   members = ["crate1", "crate2"]
+
+   [workspace.package]
+   edition = "2024"
+   rust-version = "1.85"
+
+   # Then each crate can inherit:
+   [package]
+   name = "crate1"
+   version = "0.1.0"
+   edition.workspace = true
+   rust-version.workspace = true
+   ```
+
+5. **Run cargo fix**
+
+   Automatically fix edition-related issues:
+
+   ```bash
+   cargo fix --edition
+   ```
+
+   This will:
+   - Fix deprecated patterns
+   - Update syntax where needed
+   - Add compatibility shims
+
+6. **Check for Warnings**
+
+   Review compiler warnings:
+
+   ```bash
+   cargo check --all-targets
+   ```
+
+   Common warnings:
+   - Match ergonomics changes
+   - Binding mode changes
+   - Reserved syntax warnings
+
+7. **Update Match Patterns (Rust 2024)**
+
+   **Breaking Change:** mut binding behavior changed
+
+   Before (2021):
+   ```rust
+   match &option {
+       Some(mut x) => {
+           // x is T (moved)
+       }
+       None => {}
+   }
+   ```
+
+   After (2024):
+   ```rust
+   match &option {
+       Some(mut x) => {
+           // x is &mut T (not moved)
+       }
+       None => {}
+   }
+   ```
+
+   If you need the old behavior:
+   ```rust
+   match option {  // Match on value, not reference
+       Some(mut x) => {
+           // x is T (moved)
+       }
+       None => {}
+   }
+   ```
+
+8. **Update Reserved Patterns**
+
+   Rust 2024 reserves some pattern combinations for future use:
+
+   ```rust
+   // ❌ Not allowed in 2024 (mixed ergonomics)
+   match value {
+       Some(ref x) => {}  // Error if not fully explicit
+       _ => {}
+   }
+
+   // ✅ Allowed (fully explicit)
+   match value {
+       &Some(ref x) => {}
+       _ => {}
+   }
+
+   // ✅ Or use ergonomics fully
+   match &value {
+       Some(x) => {}  // x is &T
+       _ => {}
+   }
+   ```
+
+9. **Run Tests**
+
+   Verify everything still works:
+
+   ```bash
+   cargo test --all-targets
+   ```
+
+   If tests fail:
+   - Check for match pattern changes
+   - Look for binding mode issues
+   - Review compiler errors carefully
+
+10. **Update Dependencies**
+
+    Check if dependencies support Rust 2024:
+
+    ```bash
+    cargo update
+    cargo check
+    ```
+
+    The MSRV-aware resolver (Rust 1.84+) will automatically select compatible versions based on your rust-version.
+
+11. **Enable Modern Features**
+
+    Now you can use Rust 2024 features:
+
+    ```rust
+    // Let chains
+    if let Some(x) = opt1
+        && let Some(y) = opt2
+    {
+        // ...
+    }
+
+    // Async closures
+    items.iter().map(async |item| {
+        process(item).await
+    })
+
+    // Gen blocks
+    let iter = gen {
+        yield 1;
+        yield 2;
+    };
+    ```
+
+12. **Update Lints**
+
+    Add modern lints to catch issues:
+
+    ```rust
+    // In lib.rs or main.rs
+    #![warn(rust_2024_compatibility)]
+    #![warn(let_underscore_drop)]
+    #![warn(unused_qualifications)]
+    ```
+
+13. **Provide Upgrade Summary**
+
+    ```
+    ✅ Successfully upgraded to Rust 2024 Edition!
+
+    ## Changes Made:
+
+    ### Cargo.toml Updates:
+    - Edition: 2021 → 2024
+    - Added rust-version = "1.85"
+
+    ### Code Changes:
+    - Applied automatic fixes via cargo fix
+    - Updated 3 match patterns for new ergonomics
+    - Fixed 2 reserved pattern warnings
+
+    ### Tests:
+    - All tests passing ✅
+
+    ## New Features Available:
+
+    1. **Let Chains** - Flatten nested if-let
+    2. **Async Closures** - Native async || {} syntax
+    3. **Gen Blocks** - Simplified iterators
+    4. **Improved Match Ergonomics** - Clearer semantics
+    5. **MSRV-Aware Resolver** - Automatic compatible versions
+
+    ## Next Steps:
+
+    1. Use `/rust-modernize` to apply modern patterns
+    2. Review new edition guide: https://doc.rust-lang.org/edition-guide/rust-2024/
+    3. Update CI/CD to use Rust 1.85+
+    4. Consider modernizing code patterns
+
+    ## Migration Guide:
+    See the [Rust 2024 Edition Guide](https://doc.rust-lang.org/edition-guide/rust-2024/) for details.
+    ```
+
+## Breaking Changes Checklist
+
+When upgrading to Rust 2024, be aware of:
+
+- [ ] **Match ergonomics** - mut bindings work differently
+- [ ] **Reserved patterns** - Some patterns reserved for future
+- [ ] **Temporary scopes in let chains** - Different drop order
+- [ ] **Impl trait captures** - More lifetime capture rules
+
+## Workspace Upgrade
+
+For workspaces with multiple crates:
+
+1. **Update workspace root**:
+   ```toml
+   [workspace.package]
+   edition = "2024"
+   rust-version = "1.85"
+   ```
+
+2. **Update each crate**:
+   ```toml
+   [package]
+   edition.workspace = true
+   rust-version.workspace = true
+   ```
+
+3. **Run cargo fix for each crate**:
+   ```bash
+   cargo fix --edition --workspace
+   ```
+
+## Troubleshooting
+
+### cargo fix fails
+
+If `cargo fix --edition` fails:
+1. Fix compilation errors first: `cargo check`
+2. Resolve dependency issues
+3. Try fixing one crate at a time
+4. Check for proc-macro compatibility
+
+### Tests fail after upgrade
+
+Common issues:
+1. **Match pattern changes** - Check mut bindings
+2. **Drop order changes** - Let chains have different scoping
+3. **Lifetime changes** - Impl trait captures more lifetimes
+
+### Dependencies incompatible
+
+If dependencies don't support Rust 2024:
+1. Check for updates: `cargo update`
+2. MSRV resolver should pick compatible versions
+3. File issues with dependency maintainers
+4. Consider alternatives if critical
+
+## Version Requirements
+
+- **Minimum Rust:** 1.85.0 for full Rust 2024 Edition
+- **Let chains:** 1.88.0
+- **MSRV resolver:** 1.84.0 (recommended before upgrade)
+
+## Edition Comparison
+
+| Feature | 2021 | 2024 |
+|---------|------|------|
+| Let chains | ❌ | ✅ |
+| Async closures | ❌ | ✅ |
+| Gen blocks | ❌ | ✅ |
+| Match ergonomics | Old | Improved |
+| MSRV resolver | ❌ | ✅ |
+
+## After Completion
+
+Ask the user:
+1. Did the upgrade complete successfully?
+2. Are all tests passing?
+3. Should we modernize the code to use new features?
+4. Do you want to update CI/CD configuration?