Name: migrate-dependency
Author: xarema

Prompt file imported from xarema/X-Filamenta-Python (.github/prompts/migrate-dependency.prompt.md). Fill in {{dependency}}, {{current_version}}, {{target_version}}, {{ecosystem}}, {{reason}}, {{breaking_changes}} before use. Copyright stays with the author.

Migrate Dependency

Task: Safely migrate a dependency (library, framework, tool) to a new version across the entire project.

Input Required

Dependency Details

Dependency name: {{dependency}}
Current version: {{current_version}}
Target version: {{target_version}}
Ecosystem: {{ecosystem}}

Migration Reason

Breaking Changes Known

MANDATORY: Pre-Migration Process

1. Read Documentation

Review official migration guides:

Read dependency's CHANGELOG
Read official migration/upgrade guide
Check for deprecation warnings
Identify breaking changes
Note new features/improvements

2. Impact Analysis

Create analysis report:

Location: Analysis_reports/YYYY-MM-DD_HH-mm_migrate-<dependency>-v<version>.md

Content:

Current usage across project (search codebase)
Affected files/modules
Breaking changes impact
Required code changes
Testing strategy
Rollback plan
Estimated effort

3. Backup & Branch

# Create feature branch
git checkout -b migrate-<dependency>-v<version>

# Optional: Backup database
Copy-Item "instance\filamenta. db" "instance\filamenta. db.backup-$(Get-Date -Format 'yyyyMMdd')"

Migration Process

Step 1: Update Dependency

Python (pip)

Update requirements.txt or pyproject.toml:

# Before
flask = "^2.3.0"

# After
flask = "^3.0.0"

Install:

.\. venv\Scripts\pip. exe install --upgrade flask

# Or reinstall all
.\.venv\Scripts\pip.exe install -r requirements.txt --upgrade

Lock dependencies:

.\.venv\Scripts\pip.exe freeze > requirements.lock

JavaScript (npm)

Update package.json:

{
  "dependencies": {
    "bootstrap": "^5.3.0"
  }
}

Install:

npm install bootstrap@latest

# Or
npm update bootstrap

Step 2: Find All Usages

Search codebase for affected patterns:

# Find imports (Python)
Get-ChildItem -Recurse -Include *.py | Select-String "from flask import" | Select-Object -Unique Path

# Find CDN links (HTML)
Get-ChildItem -Recurse -Include *.html | Select-String "bootstrap@5. 2" | Select-Object -Unique Path

# Find API usage
Get-ChildItem -Recurse -Include *.py | Select-String "deprecated_function"

Document findings in analysis report.

Step 3: Apply Breaking Changes

Common migration patterns:

Example: Flask 2.x → 3.x

Breaking change: flask. json module reorganized

Before (Flask 2.x):

from flask. json import jsonify

After (Flask 3.x):

from flask import jsonify  # Still works
# Or
import json
from flask import Response

def my_route():
    return Response(json.dumps(data), mimetype="application/json")

Example: Bootstrap 5.2 → 5.3

Breaking change: Utility classes renamed

Before:

<div class="ms-auto">... </div>  <!-- margin-start -->

After (still works, but deprecated warning):

<div class="ms-auto">...</div>  <!-- Still supported -->

New recommended (if breaking in future):

<div class="margin-start-auto">...</div>

Step 4: Update Code Systematically

For each affected file:

Open file
Apply required changes (from breaking changes list)
Update imports/API calls
Remove deprecated code
Add file header update (Last modified, commit)
Run linters on that file
Test that file's functionality

Example workflow per file:

# Edit file
code backend/src/routes/users.py

# After changes, lint
. \.venv\Scripts\ruff. exe check backend/src/routes/users.py
. \.venv\Scripts\mypy. exe backend/src/routes/users.py

# Run related tests
.\.venv\Scripts\pytest.exe tests/test_users.py -v

Step 5: Update Templates/Frontend (if applicable)

For framework migrations (Bootstrap, HTMX, etc.):

Update CDN links:

<!-- Before -->
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.2.3/dist/css/bootstrap.min.css" rel="stylesheet">

<!-- After -->
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet">

Update class names/attributes:

<!-- If breaking change -->
<!-- Before -->
<div class="old-class">...</div>

<!-- After -->
<div class="new-class">...</div>

Search and replace carefully:

# Find all affected templates
Get-ChildItem -Recurse -Include *.html | Select-String "old-class"

# Manual review + replace (DO NOT use automated replace without review)

Step 6: Run Full Test Suite

Automated tests:

# Python tests
.\.venv\Scripts\pytest.exe -v --cov

# Linters
.\.venv\Scripts\ruff.exe check . 
.\.venv\Scripts\ruff.exe format --check .
.\.venv\Scripts\mypy.exe backend/src

# Frontend tests (if applicable)
npm run lint
npm run test

Fix all failures before continuing.

Step 7: Manual Testing

Kill servers and test:

# Kill servers
Get-Process python. exe -ErrorAction SilentlyContinue | Stop-Process -Force -ErrorAction SilentlyContinue

# Dev mode testing
.\.venv\Scripts\python.exe backend\src\app.py

Test checklist:

All routes accessible
No console errors (browser DevTools)
No server errors (terminal logs)
UI displays correctly (all pages)
Forms submit successfully
AJAX/HTMX interactions work
Translations display
Responsive design intact (test mobile viewport)

Repeat in prod mode:

Get-Process python.exe -ErrorAction SilentlyContinue | Stop-Process -Force -ErrorAction SilentlyContinue
. \.venv\Scripts\python. exe run_prod. py

Step 8: Performance Testing (if major version)

Compare before/after:

Metrics to check:

Page load times
Database query performance
Memory usage
Bundle size (frontend)

Tools:

# Backend profiling (if needed)
.\.venv\Scripts\pip.exe install flask-profiler

# Frontend bundle size
npm run build
# Check dist/ folder size

Step 9: Documentation

Update CHANGELOG. md:

## [Unreleased]

### Changed
- **BREAKING:** Migrated to Flask 3.0.0 (#issue)
  - Updated all imports and API calls
  - Removed deprecated `flask.json` usage
  - Tested all endpoints
  - No user-facing changes
  
### Dependencies
- Upgraded Flask from 2.3.0 to 3.0.0
- Upgraded SQLAlchemy from 1.4.x to 2.0.x (compatible with Flask 3)

Update requirements.txt / package.json:

Ensure new versions pinned
Update lock files

Create migration report:

Location: Analysis_reports/YYYY-MM-DD_HH-mm_migrate-<dependency>-complete.md
Content:
- Migration summary
- Files changed (list)
- Breaking changes applied
- Test results
- Performance impact (if measured)
- Issues encountered + solutions
- Rollback notes

Rollback Plan

If migration fails:

1. Revert Code Changes

# Discard all changes
git checkout . 

# Or revert to specific commit
git revert <commit-hash>

2. Reinstall Old Dependency

Python:

# Edit requirements.txt (restore old version)
# Then reinstall
.\.venv\Scripts\pip.exe install -r requirements.txt --force-reinstall

JavaScript:

npm install <dependency>@<old-version>

3. Restore Database (if needed)

Copy-Item "instance\filamenta.db. backup-YYYYMMDD" "instance\filamenta.db" -Force

4. Test Rollback

Run tests
Start server
Verify functionality restored

Common Migration Scenarios

Scenario 1: Flask 2.x → 3.x

Breaking changes:

flask.json module reorganized
Some Werkzeug APIs changed
Click 8. x required

Fix:

# Update imports
from flask import jsonify  # Still works in 3.x

# Update Click commands (if using CLI)
import click
# (No changes needed for basic usage)

Scenario 2: Bootstrap 5.2 → 5.3

Breaking changes:

Minimal (mostly additions)
Some utility classes deprecated (warnings)

Fix:

<!-- Update CDN version -->
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet">

<!-- Review deprecation warnings in browser console -->
<!-- Update deprecated classes if found -->

Scenario 3: SQLAlchemy 1.4 → 2.0

Breaking changes:

New query API (ORM)
engine. execute() removed → use session.execute()
Query object methods changed

Fix:

# Before (1.4)
users = User.query.filter_by(active=True).all()
result = db.engine.execute("SELECT * FROM users")

# After (2.0)
users = db.session.execute(
    db.select(User).filter_by(active=True)
).scalars().all()

result = db.session.execute(db.text("SELECT * FROM users"))

Files Created/Modified

requirements.txt (or pyproject.toml)          ← Update dependency version
package.json                                  ← Update dependency version (if JS)
backend/src/**/*.py                           ← Apply breaking changes
backend/src/templates/**/*.html               ← Update CDN/class names (if frontend)
tests/**/*.py                                 ← Update test assertions (if API changed)
CHANGELOG.md                                  ← Document migration
Analysis_reports/<timestamp>_migrate-<dep>.md ← Migration report

Validation Checklist

Don'ts

❌ Update dependency without reading changelog
❌ Skip impact analysis
❌ Apply changes without testing each file
❌ Use automated find-replace for code (manual review required)
❌ Skip manual testing
❌ Commit without all tests passing
❌ Forget to update CHANGELOG
❌ Leave deprecated code (if removal is safe)
❌ Ignore deprecation warnings
❌ Skip rollback plan preparation

References

.github/copilot-instructions. md — General rules
.github/python.instructions.md — Python dependencies
.github/frontend.instructions.md — Frontend dependencies
.github/workflow-rules.md — Testing workflow
Dependency's official changelog/migration guide

# Migrate Dependency **Task:** Safely migrate a dependency (library, framework, tool) to a new version across the entire project. --- ## Input Required ### Dependency Details - **Dependency name:** {{dependency}} - **Current version:** {{current_version}} - **Target version:** {{target_version}} - **Ecosystem:** {{ecosystem}} ### Migration Reason {{reason}} ### Breaking Changes Known {{breaking_changes}} --- ## MANDATORY: Pre-Migration Process ### 1. Read Documentation **Review official migration guides:** - [ ] Read dependency's CHANGELOG - [ ] Read official migration/upgrade guide - [ ] Check for deprecation warnings - [ ] Identify breaking changes - [ ] Note new features/improvements ### 2. Impact Analysis **Create analysis report:** - Location: `Analysis_reports/YYYY-MM-DD_HH-mm_migrate-<dependency>-v<version>.md` **Content:** - Current usage across project (search codebase) - Affected files/modules - Breaking changes impact - Required code changes - Testing strategy - Rollback plan - Estimated effort ### 3. Backup & Branch ```powershell # Create feature branch git checkout -b migrate-<dependency>-v<version> # Optional: Backup database Copy-Item "instance\filamenta. db" "instance\filamenta. db.backup-$(Get-Date -Format 'yyyyMMdd')" ``` --- ## Migration Process ### Step 1: Update Dependency #### Python (pip) **Update `requirements.txt` or `pyproject.toml`:** ```toml # Before flask = "^2.3.0" # After flask = "^3.0.0" ``` **Install:** ```powershell .\. venv\Scripts\pip. exe install --upgrade flask # Or reinstall all .\.venv\Scripts\pip.exe install -r requirements.txt --upgrade ``` **Lock dependencies:** ```powershell .\.venv\Scripts\pip.exe freeze > requirements.lock ``` #### JavaScript (npm) **Update `package.json`:** ```json { "dependencies": { "bootstrap": "^5.3.0" } } ``` **Install:** ```powershell npm install bootstrap@latest # Or npm update bootstrap ``` --- ### Step 2: Find All Usages **Search codebase for affected patterns:** ```powershell # Find imports (Python) Get-ChildItem -Recurse -Include *.py | Select-String "from flask import" | Select-Object -Unique Path # Find CDN links (HTML) Get-ChildItem -Recurse -Include *.html | Select-String "bootstrap@5. 2" | Select-Object -Unique Path # Find API usage Get-ChildItem -Recurse -Include *.py | Select-String "deprecated_function" ``` **Document findings in analysis report.** --- ### Step 3: Apply Breaking Changes **Common migration patterns:** #### Example: Flask 2.x → 3.x **Breaking change: `flask. json` module reorganized** **Before (Flask 2.x):** ```python from flask. json import jsonify ``` **After (Flask 3.x):** ```python from flask import jsonify # Still works # Or import json from flask import Response def my_route(): return Response(json.dumps(data), mimetype="application/json") ``` #### Example: Bootstrap 5.2 → 5.3 **Breaking change: Utility classes renamed** **Before:** ```html <div class="ms-auto">... </div>  ``` **After (still works, but deprecated warning):** ```html <div class="ms-auto">...</div>  ``` **New recommended (if breaking in future):** ```html <div class="margin-start-auto">...</div> ``` --- ### Step 4: Update Code Systematically **For each affected file:** 1. **Open file** 2. **Apply required changes** (from breaking changes list) 3. **Update imports/API calls** 4. **Remove deprecated code** 5. **Add file header update** (Last modified, commit) 6. **Run linters** on that file 7. **Test that file's functionality** **Example workflow per file:** ```powershell # Edit file code backend/src/routes/users.py # After changes, lint . \.venv\Scripts\ruff. exe check backend/src/routes/users.py . \.venv\Scripts\mypy. exe backend/src/routes/users.py # Run related tests .\.venv\Scripts\pytest.exe tests/test_users.py -v ``` --- ### Step 5: Update Templates/Frontend (if applicable) **For framework migrations (Bootstrap, HTMX, etc.):** **Update CDN links:** ```html  <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.2.3/dist/css/bootstrap.min.css" rel="stylesheet">  <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet"> ``` **Update class names/attributes:** ```html   <div class="old-class">...</div>  <div class="new-class">...</div> ``` **Search and replace carefully:** ```powershell # Find all affected templates Get-ChildItem -Recurse -Include *.html | Select-String "old-class" # Manual review + replace (DO NOT use automated replace without review) ``` --- ### Step 6: Run Full Test Suite **Automated tests:** ```powershell # Python tests .\.venv\Scripts\pytest.exe -v --cov # Linters .\.venv\Scripts\ruff.exe check . .\.venv\Scripts\ruff.exe format --check . .\.venv\Scripts\mypy.exe backend/src # Frontend tests (if applicable) npm run lint npm run test ``` **Fix all failures before continuing.** --- ### Step 7: Manual Testing **Kill servers and test:** ```powershell # Kill servers Get-Process python. exe -ErrorAction SilentlyContinue | Stop-Process -Force -ErrorAction SilentlyContinue # Dev mode testing .\.venv\Scripts\python.exe backend\src\app.py ``` **Test checklist:** - [ ] All routes accessible - [ ] No console errors (browser DevTools) - [ ] No server errors (terminal logs) - [ ] UI displays correctly (all pages) - [ ] Forms submit successfully - [ ] AJAX/HTMX interactions work - [ ] Translations display - [ ] Responsive design intact (test mobile viewport) **Repeat in prod mode:** ```powershell Get-Process python.exe -ErrorAction SilentlyContinue | Stop-Process -Force -ErrorAction SilentlyContinue . \.venv\Scripts\python. exe run_prod. py ``` --- ### Step 8: Performance Testing (if major version) **Compare before/after:** **Metrics to check:** - Page load times - Database query performance - Memory usage - Bundle size (frontend) **Tools:** ```powershell # Backend profiling (if needed) .\.venv\Scripts\pip.exe install flask-profiler # Frontend bundle size npm run build # Check dist/ folder size ``` --- ### Step 9: Documentation **Update CHANGELOG. md:** ```markdown ## [Unreleased] ### Changed - **BREAKING:** Migrated to Flask 3.0.0 (#issue) - Updated all imports and API calls - Removed deprecated `flask.json` usage - Tested all endpoints - No user-facing changes ### Dependencies - Upgraded Flask from 2.3.0 to 3.0.0 - Upgraded SQLAlchemy from 1.4.x to 2.0.x (compatible with Flask 3) ``` **Update `requirements.txt` / `package.json`:** - Ensure new versions pinned - Update lock files **Create migration report:** - Location: `Analysis_reports/YYYY-MM-DD_HH-mm_migrate-<dependency>-complete.md` - Content: - Migration summary - Files changed (list) - Breaking changes applied - Test results - Performance impact (if measured) - Issues encountered + solutions - Rollback notes --- ## Rollback Plan **If migration fails:** ### 1. Revert Code Changes ```powershell # Discard all changes git checkout . # Or revert to specific commit git revert <commit-hash> ``` ### 2. Reinstall Old Dependency **Python:** ```powershell # Edit requirements.txt (restore old version) # Then reinstall .\.venv\Scripts\pip.exe install -r requirements.txt --force-reinstall ``` **JavaScript:** ```powershell npm install <dependency>@<old-version> ``` ### 3. Restore Database (if needed) ```powershell Copy-Item "instance\filamenta.db. backup-YYYYMMDD" "instance\filamenta.db" -Force ``` ### 4. Test Rollback - Run tests - Start server - Verify functionality restored --- ## Common Migration Scenarios ### Scenario 1: Flask 2.x → 3.x **Breaking changes:** - `flask.json` module reorganized - Some Werkzeug APIs changed - Click 8. x required **Fix:** ```python # Update imports from flask import jsonify # Still works in 3.x # Update Click commands (if using CLI) import click # (No changes needed for basic usage) ``` --- ### Scenario 2: Bootstrap 5.2 → 5.3 **Breaking changes:** - Minimal (mostly additions) - Some utility classes deprecated (warnings) **Fix:** ```html  <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet">   ``` --- ### Scenario 3: SQLAlchemy 1.4 → 2.0 **Breaking changes:** - New query API (ORM) - `engine. execute()` removed → use `session.execute()` - `Query` object methods changed **Fix:** ```python # Before (1.4) users = User.query.filter_by(active=True).all() result = db.engine.execute("SELECT * FROM users") # After (2.0) users = db.session.execute( db.select(User).filter_by(active=True) ).scalars().all() result = db.session.execute(db.text("SELECT * FROM users")) ``` --- ## Files Created/Modified ``` requirements.txt (or pyproject.toml) ← Update dependency version package.json ← Update dependency version (if JS) backend/src/**/*.py ← Apply breaking changes backend/src/templates/**/*.html ← Update CDN/class names (if frontend) tests/**/*.py ← Update test assertions (if API changed) CHANGELOG.md ← Document migration Analysis_reports/<timestamp>_migrate-<dep>.md ← Migration report ``` --- ## Validation Checklist - [ ] Analysis report created (pre-migration) - [ ] Feature branch created - [ ] Backup created (database, if applicable) - [ ] Official migration guide read - [ ] Breaking changes identified - [ ] Dependency updated in manifest files - [ ] All usages found and documented - [ ] Code changes applied systematically - [ ] File headers updated - [ ] Linters pass (Ruff, Mypy, npm lint) - [ ] All automated tests pass - [ ] Manual testing complete (dev mode) - [ ] Manual testing complete (prod mode) - [ ] No console errors - [ ] No server errors/warnings - [ ] Performance acceptable (if measured) - [ ] CHANGELOG. md updated - [ ] Migration report created - [ ] Rollback plan documented and tested --- ## Don'ts - ❌ Update dependency without reading changelog - ❌ Skip impact analysis - ❌ Apply changes without testing each file - ❌ Use automated find-replace for code (manual review required) - ❌ Skip manual testing - ❌ Commit without all tests passing - ❌ Forget to update CHANGELOG - ❌ Leave deprecated code (if removal is safe) - ❌ Ignore deprecation warnings - ❌ Skip rollback plan preparation --- ## References - `.github/copilot-instructions. md` — General rules - `.github/python.instructions.md` — Python dependencies - `.github/frontend.instructions.md` — Frontend dependencies - `.github/workflow-rules.md` — Testing workflow - Dependency's official changelog/migration guide --- **License:** AGPL-3.0-or-later **Copyright:** © 2025 XAREMA. All rights reserved.

{ "prompt": "# Migrate Dependency\n\n**Task:** Safely migrate a dependency (library, framework, tool) to a new version across the entire project.\n\n---\n\n## Input Required\n\n### Dependency Details\n- **Dependency name:** {{dependency}}\n- **Current version:** {{current_version}}\n- **Target version:** {{target_version}}\n- **Ecosystem:** {{ecosystem}}\n\n### Migration Reason\n{{reason}}\n\n### Breaking Changes Known\n{{breaking_changes}}\n\n---\n\n## MANDATORY: Pre-Migration Process\n\n### 1. Read Documentation\n\n**Review official migration guides:**\n- [ ] Read dependency's CHANGELOG\n- [ ] Read official migration/upgrade guide\n- [ ] Check for deprecation warnings\n- [ ] Identify breaking changes\n- [ ] Note new features/improvements\n\n### 2. Impact Analysis\n\n**Create analysis report:**\n- Location: `Analysis_reports/YYYY-MM-DD_HH-mm_migrate-<dependency>-v<version>.md`\n\n**Content:**\n- Current usage across project (search codebase)\n- Affected files/modules\n- Breaking changes impact\n- Required code changes\n- Testing strategy\n- Rollback plan\n- Estimated effort\n\n### 3. Backup & Branch\n\n```powershell\n# Create feature branch\ngit checkout -b migrate-<dependency>-v<version>\n\n# Optional: Backup database\nCopy-Item \"instance\\filamenta. db\" \"instance\\filamenta. db.backup-$(Get-Date -Format 'yyyyMMdd')\"\n```\n\n---\n\n## Migration Process\n\n### Step 1: Update Dependency\n\n#### Python (pip)\n\n**Update `requirements.txt` or `pyproject.toml`:**\n\n```toml\n# Before\nflask = \"^2.3.0\"\n\n# After\nflask = \"^3.0.0\"\n```\n\n**Install:**\n```powershell\n.\\. venv\\Scripts\\pip. exe install --upgrade flask\n\n# Or reinstall all\n.\\.venv\\Scripts\\pip.exe install -r requirements.txt --upgrade\n```\n\n**Lock dependencies:**\n```powershell\n.\\.venv\\Scripts\\pip.exe freeze > requirements.lock\n```\n\n#### JavaScript (npm)\n\n**Update `package.json`:**\n```json\n{\n \"dependencies\": {\n \"bootstrap\": \"^5.3.0\"\n }\n}\n```\n\n**Install:**\n```powershell\nnpm install bootstrap@latest\n\n# Or\nnpm update bootstrap\n```\n\n---\n\n### Step 2: Find All Usages\n\n**Search codebase for affected patterns:**\n\n```powershell\n# Find imports (Python)\nGet-ChildItem -Recurse -Include *.py | Select-String \"from flask import\" | Select-Object -Unique Path\n\n# Find CDN links (HTML)\nGet-ChildItem -Recurse -Include *.html | Select-String \"bootstrap@5. 2\" | Select-Object -Unique Path\n\n# Find API usage\nGet-ChildItem -Recurse -Include *.py | Select-String \"deprecated_function\"\n```\n\n**Document findings in analysis report.**\n\n---\n\n### Step 3: Apply Breaking Changes\n\n**Common migration patterns:**\n\n#### Example: Flask 2.x → 3.x\n\n**Breaking change: `flask. json` module reorganized**\n\n**Before (Flask 2.x):**\n```python\nfrom flask. json import jsonify\n```\n\n**After (Flask 3.x):**\n```python\nfrom flask import jsonify # Still works\n# Or\nimport json\nfrom flask import Response\n\ndef my_route():\n return Response(json.dumps(data), mimetype=\"application/json\")\n```\n\n#### Example: Bootstrap 5.2 → 5.3\n\n**Breaking change: Utility classes renamed**\n\n**Before:**\n```html\n<div class=\"ms-auto\">... </div> \n```\n\n**After (still works, but deprecated warning):**\n```html\n<div class=\"ms-auto\">...</div> \n```\n\n**New recommended (if breaking in future):**\n```html\n<div class=\"margin-start-auto\">...</div>\n```\n\n---\n\n### Step 4: Update Code Systematically\n\n**For each affected file:**\n\n1. **Open file**\n2. **Apply required changes** (from breaking changes list)\n3. **Update imports/API calls**\n4. **Remove deprecated code**\n5. **Add file header update** (Last modified, commit)\n6. **Run linters** on that file\n7. **Test that file's functionality**\n\n**Example workflow per file:**\n\n```powershell\n# Edit file\ncode backend/src/routes/users.py\n\n# After changes, lint\n. \\.venv\\Scripts\\ruff. exe check backend/src/routes/users.py\n. \\.venv\\Scripts\\mypy. exe backend/src/routes/users.py\n\n# Run related tests\n.\\.venv\\Scripts\\pytest.exe tests/test_users.py -v\n```\n\n---\n\n### Step 5: Update Templates/Frontend (if applicable)\n\n**For framework migrations (Bootstrap, HTMX, etc.):**\n\n**Update CDN links:**\n```html\n\n<link href=\"https://cdn.jsdelivr.net/npm/bootstrap@5.2.3/dist/css/bootstrap.min.css\" rel=\"stylesheet\">\n\n\n<link href=\"https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css\" rel=\"stylesheet\">\n```\n\n**Update class names/attributes:**\n```html\n\n\n<div class=\"old-class\">...</div>\n\n\n<div class=\"new-class\">...</div>\n```\n\n**Search and replace carefully:**\n```powershell\n# Find all affected templates\nGet-ChildItem -Recurse -Include *.html | Select-String \"old-class\"\n\n# Manual review + replace (DO NOT use automated replace without review)\n```\n\n---\n\n### Step 6: Run Full Test Suite\n\n**Automated tests:**\n```powershell\n# Python tests\n.\\.venv\\Scripts\\pytest.exe -v --cov\n\n# Linters\n.\\.venv\\Scripts\\ruff.exe check . \n.\\.venv\\Scripts\\ruff.exe format --check .\n.\\.venv\\Scripts\\mypy.exe backend/src\n\n# Frontend tests (if applicable)\nnpm run lint\nnpm run test\n```\n\n**Fix all failures before continuing.**\n\n---\n\n### Step 7: Manual Testing\n\n**Kill servers and test:**\n\n```powershell\n# Kill servers\nGet-Process python. exe -ErrorAction SilentlyContinue | Stop-Process -Force -ErrorAction SilentlyContinue\n\n# Dev mode testing\n.\\.venv\\Scripts\\python.exe backend\\src\\app.py\n```\n\n**Test checklist:**\n- [ ] All routes accessible\n- [ ] No console errors (browser DevTools)\n- [ ] No server errors (terminal logs)\n- [ ] UI displays correctly (all pages)\n- [ ] Forms submit successfully\n- [ ] AJAX/HTMX interactions work\n- [ ] Translations display\n- [ ] Responsive design intact (test mobile viewport)\n\n**Repeat in prod mode:**\n```powershell\nGet-Process python.exe -ErrorAction SilentlyContinue | Stop-Process -Force -ErrorAction SilentlyContinue\n. \\.venv\\Scripts\\python. exe run_prod. py\n```\n\n---\n\n### Step 8: Performance Testing (if major version)\n\n**Compare before/after:**\n\n**Metrics to check:**\n- Page load times\n- Database query performance\n- Memory usage\n- Bundle size (frontend)\n\n**Tools:**\n```powershell\n# Backend profiling (if needed)\n.\\.venv\\Scripts\\pip.exe install flask-profiler\n\n# Frontend bundle size\nnpm run build\n# Check dist/ folder size\n```\n\n---\n\n### Step 9: Documentation\n\n**Update CHANGELOG. md:**\n\n```markdown\n## [Unreleased]\n\n### Changed\n- **BREAKING:** Migrated to Flask 3.0.0 (#issue)\n - Updated all imports and API calls\n - Removed deprecated `flask.json` usage\n - Tested all endpoints\n - No user-facing changes\n \n### Dependencies\n- Upgraded Flask from 2.3.0 to 3.0.0\n- Upgraded SQLAlchemy from 1.4.x to 2.0.x (compatible with Flask 3)\n```\n\n**Update `requirements.txt` / `package.json`:**\n- Ensure new versions pinned\n- Update lock files\n\n**Create migration report:**\n- Location: `Analysis_reports/YYYY-MM-DD_HH-mm_migrate-<dependency>-complete.md`\n- Content: \n - Migration summary\n - Files changed (list)\n - Breaking changes applied\n - Test results\n - Performance impact (if measured)\n - Issues encountered + solutions\n - Rollback notes\n\n---\n\n## Rollback Plan\n\n**If migration fails:**\n\n### 1. Revert Code Changes\n\n```powershell\n# Discard all changes\ngit checkout . \n\n# Or revert to specific commit\ngit revert <commit-hash>\n```\n\n### 2. Reinstall Old Dependency\n\n**Python:**\n```powershell\n# Edit requirements.txt (restore old version)\n# Then reinstall\n.\\.venv\\Scripts\\pip.exe install -r requirements.txt --force-reinstall\n```\n\n**JavaScript:**\n```powershell\nnpm install <dependency>@<old-version>\n```\n\n### 3. Restore Database (if needed)\n\n```powershell\nCopy-Item \"instance\\filamenta.db. backup-YYYYMMDD\" \"instance\\filamenta.db\" -Force\n```\n\n### 4. Test Rollback\n\n- Run tests\n- Start server\n- Verify functionality restored\n\n---\n\n## Common Migration Scenarios\n\n### Scenario 1: Flask 2.x → 3.x\n\n**Breaking changes:**\n- `flask.json` module reorganized\n- Some Werkzeug APIs changed\n- Click 8. x required\n\n**Fix:**\n```python\n# Update imports\nfrom flask import jsonify # Still works in 3.x\n\n# Update Click commands (if using CLI)\nimport click\n# (No changes needed for basic usage)\n```\n\n---\n\n### Scenario 2: Bootstrap 5.2 → 5.3\n\n**Breaking changes:**\n- Minimal (mostly additions)\n- Some utility classes deprecated (warnings)\n\n**Fix:**\n```html\n\n<link href=\"https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css\" rel=\"stylesheet\">\n\n\n\n```\n\n---\n\n### Scenario 3: SQLAlchemy 1.4 → 2.0\n\n**Breaking changes:**\n- New query API (ORM)\n- `engine. execute()` removed → use `session.execute()`\n- `Query` object methods changed\n\n**Fix:**\n```python\n# Before (1.4)\nusers = User.query.filter_by(active=True).all()\nresult = db.engine.execute(\"SELECT * FROM users\")\n\n# After (2.0)\nusers = db.session.execute(\n db.select(User).filter_by(active=True)\n).scalars().all()\n\nresult = db.session.execute(db.text(\"SELECT * FROM users\"))\n```\n\n---\n\n## Files Created/Modified\n\n```\nrequirements.txt (or pyproject.toml) ← Update dependency version\npackage.json ← Update dependency version (if JS)\nbackend/src/**/*.py ← Apply breaking changes\nbackend/src/templates/**/*.html ← Update CDN/class names (if frontend)\ntests/**/*.py ← Update test assertions (if API changed)\nCHANGELOG.md ← Document migration\nAnalysis_reports/<timestamp>_migrate-<dep>.md ← Migration report\n```\n\n---\n\n## Validation Checklist\n\n- [ ] Analysis report created (pre-migration)\n- [ ] Feature branch created\n- [ ] Backup created (database, if applicable)\n- [ ] Official migration guide read\n- [ ] Breaking changes identified\n- [ ] Dependency updated in manifest files\n- [ ] All usages found and documented\n- [ ] Code changes applied systematically\n- [ ] File headers updated\n- [ ] Linters pass (Ruff, Mypy, npm lint)\n- [ ] All automated tests pass\n- [ ] Manual testing complete (dev mode)\n- [ ] Manual testing complete (prod mode)\n- [ ] No console errors\n- [ ] No server errors/warnings\n- [ ] Performance acceptable (if measured)\n- [ ] CHANGELOG. md updated\n- [ ] Migration report created\n- [ ] Rollback plan documented and tested\n\n---\n\n## Don'ts\n\n- ❌ Update dependency without reading changelog\n- ❌ Skip impact analysis\n- ❌ Apply changes without testing each file\n- ❌ Use automated find-replace for code (manual review required)\n- ❌ Skip manual testing\n- ❌ Commit without all tests passing\n- ❌ Forget to update CHANGELOG\n- ❌ Leave deprecated code (if removal is safe)\n- ❌ Ignore deprecation warnings\n- ❌ Skip rollback plan preparation\n\n---\n\n## References\n\n- `.github/copilot-instructions. md` — General rules\n- `.github/python.instructions.md` — Python dependencies\n- `.github/frontend.instructions.md` — Frontend dependencies\n- `.github/workflow-rules.md` — Testing workflow\n- Dependency's official changelog/migration guide\n\n---\n\n**License:** AGPL-3.0-or-later \n**Copyright:** © 2025 XAREMA. All rights reserved.", "variables": [ "dependency", "current_version", "target_version", "ecosystem", "reason", "breaking_changes" ], "notes": "Migrate a dependency to a new version across the entire codebase Mode: agent.", "metadata": { "source": { "provider": "github-prompts", "repository": "https://github.com/xarema/X-Filamenta-Python", "path": ".github/prompts/migrate-dependency.prompt.md", "ref": "1eae3c246eedd39271e7e37332c8a58b1c5ef2f4", "url": "https://github.com/xarema/X-Filamenta-Python/blob/1eae3c246eedd39271e7e37332c8a58b1c5ef2f4/.github/prompts/migrate-dependency.prompt.md", "key": "xarema/X-Filamenta-Python/.github/prompts/migrate-dependency.prompt.md" } } }

About

Migrate Dependency

Input Required

Dependency Details

Migration Reason

Breaking Changes Known

MANDATORY: Pre-Migration Process

1. Read Documentation

2. Impact Analysis

3. Backup & Branch

Migration Process

Step 1: Update Dependency

Python (pip)

JavaScript (npm)

Step 2: Find All Usages

Step 3: Apply Breaking Changes

Example: Flask 2.x → 3.x

Example: Bootstrap 5.2 → 5.3

Step 4: Update Code Systematically

Step 5: Update Templates/Frontend (if applicable)

Step 6: Run Full Test Suite

Step 7: Manual Testing

Step 8: Performance Testing (if major version)

Step 9: Documentation

Rollback Plan

1. Revert Code Changes

2. Reinstall Old Dependency

3. Restore Database (if needed)

4. Test Rollback

Common Migration Scenarios

Scenario 1: Flask 2.x → 3.x

Scenario 2: Bootstrap 5.2 → 5.3

Scenario 3: SQLAlchemy 1.4 → 2.0

Files Created/Modified

Validation Checklist

Don'ts

References

Install migrate-dependency and it becomes one more candidate the router can pick - when it fits.

Use it

Manifest

Reviews