NetBeans upgrade results in default settings after userdir incompatibility

Answer to the Core Questions

1. Criteria that should trigger a backup prompt

• Schema version mismatch: The installer detects that the current userdir contains a configuration schema older than the minimum required by the new release.
• File corruption or unreadable files: Any essential config file (e.g., config.xml, options.xml) fails to parse or is unreadable after the upgrade starts.
• Read‑only or permission‑denied userdir: The upgrade process cannot write to the existing userdir, which would prevent migration of new defaults.
• Explicit user request: The user opts to preserve the current environment (via a command‑line flag or GUI checkbox) before launching the upgrade.

2. Safe automatic rollback mechanism

1. Pre‑upgrade copy: Before any migration scripts run, copy the entire ~/.netbeans/ (or %APPDATA%\NetBeans\ on Windows) to a timestamped directory such as ~/.netbeans/backup-YYYYMMDD-HHMMSS/.
2. Atomic flag file: Create a small file named upgrade.in-progress inside the backup directory to signal that a rollback may be needed.
3. Migration attempt: Run the standard upgrade process. If it completes successfully, delete the upgrade.in-progress flag.
4. Rollback trigger: If the upgrade exits with a non‑zero code or logs an incompatibility error, automatically delete the partially migrated userdir and copy the backup directory back to its original location.
5. Cleanup: Remove the backup directory after a successful restoration, or keep it for a configurable retention period.

All file operations use the operating system’s native copy APIs, ensuring that permissions, timestamps, and symlinks are preserved. No manual filesystem work is required from the user.

3. Impact on upgrade time and disk usage

• Time: The backup step adds a linear cost proportional to the size of the userdir. For typical installations (~10 MB) the copy takes <5 seconds; for large, heavily customized setups (hundreds of MB) it may take a minute or more.
• Disk space: During the upgrade, disk usage temporarily doubles because the original and backup copies coexist. After a successful upgrade the backup can be deleted, restoring the original footprint. If a rollback occurs, the disk usage remains the same as before the upgrade.
• User experience: The prompt can be shown in a dialog that offers “Backup now and continue” or “Skip backup.” A silent backup (no prompt) is only advisable when the criteria above are met automatically, to avoid surprises.

Practical Steps for the Current Situation

1. Check the upgrade log: Look for messages like Incompatible userdir: schema version X required, found Y to confirm the exact issue.
2. Verify backup existence: Inspect ~/.netbeans/backup-*/ for a recent copy. If none exists, create one manually: cp -r ~/.netbeans ~/.netbeans/backup-$(date +%Y%m%d-%H%M%S).
3. Restore manually if needed: Delete the current ~/.netbeans directory and copy the backup back: rm -rf ~/.netbeans && cp -r ~/.netbeans/backup-YYYYMMDD-HHMMSS ~/.netbeans.
4. Retry upgrade: Run the installer again; the backup prompt should appear automatically if the criteria are met.

These steps avoid manual editing of configuration files and keep the IDE in a consistent state.

Missing Diagnostic Detail

To fine‑tune the recommendation, could you confirm the approximate size of your current ~/.netbeans directory? This will help estimate the backup duration and temporary disk usage more accurately.