237
MIGRATION.md
Archivo normal
237
MIGRATION.md
Archivo normal
@@ -0,0 +1,237 @@
|
||||
# Migración a WebExtensions (Versión 3.0)
|
||||
|
||||
## Resumen de cambios
|
||||
|
||||
La extensión Classic Add-ons Archive ha sido modernizada desde el sistema legacy XUL/XPCOM a WebExtensions para ser compatible con navegadores modernos Firefox (57+) y Chrome.
|
||||
|
||||
## Cambios principales
|
||||
|
||||
### 1. Sistema de manifiesto
|
||||
|
||||
**ANTES (Legacy):**
|
||||
- `install.rdf` - Manifiesto XML
|
||||
- `chrome.manifest` - Registro de recursos chrome://
|
||||
- `bootstrap.js` - Script de arranque con XPCOM
|
||||
|
||||
**AHORA (WebExtensions):**
|
||||
- `manifest.json` - Manifiesto estándar WebExtensions (Manifest V2)
|
||||
- `background.js` - Script de fondo con APIs modernas
|
||||
|
||||
### 2. Protocolo de navegación
|
||||
|
||||
**ANTES:**
|
||||
```
|
||||
caa:list
|
||||
caa:addon/some-addon
|
||||
caa:about
|
||||
```
|
||||
|
||||
**AHORA:**
|
||||
```
|
||||
chrome-extension://.../content/ca-archive.html#list
|
||||
chrome-extension://.../content/ca-archive.html#addon/some-addon
|
||||
chrome-extension://.../content/ca-archive.html#about
|
||||
```
|
||||
|
||||
La navegación ahora usa hash (#) en lugar de un protocolo personalizado.
|
||||
|
||||
### 3. Acceso a recursos
|
||||
|
||||
**ANTES:**
|
||||
```html
|
||||
<link href="chrome://ca-archive/skin/ca-archive.css">
|
||||
<script src="chrome://ca-archive/content/ca-archive.js">
|
||||
```
|
||||
|
||||
**AHORA:**
|
||||
```html
|
||||
<link href="../skin/ca-archive.css">
|
||||
<script src="ca-archive.js">
|
||||
```
|
||||
|
||||
Todos los recursos usan rutas relativas.
|
||||
|
||||
### 4. Base de datos SQLite
|
||||
|
||||
**ANTES:**
|
||||
- Acceso directo a SQLite usando `mozIStorageService`
|
||||
- Almacenamiento en perfil del usuario
|
||||
|
||||
**AHORA:**
|
||||
- Usa `sql.js` (SQLite compilado a JavaScript/WebAssembly)
|
||||
- Base de datos almacenada en `browser.storage.local`
|
||||
- Primera carga descarga y cachea la DB
|
||||
|
||||
### 5. APIs reemplazadas
|
||||
|
||||
| Legacy API | WebExtensions API |
|
||||
|------------|-------------------|
|
||||
| `Components.utils` | Scripts estándar ES6 |
|
||||
| `Services.prefs` | `browser.storage.local` |
|
||||
| `Services.wm` | `browser.tabs` y `browser.windows` |
|
||||
| `mozIStorageService` | `sql.js` |
|
||||
| `XPCOMUtils` | APIs nativas del navegador |
|
||||
| `Cu.import()` | `import` / carga dinámica de scripts |
|
||||
|
||||
### 6. Interfaz de usuario
|
||||
|
||||
**ANTES:**
|
||||
- Botón insertado directamente en la barra de herramientas
|
||||
- Menú en Tools
|
||||
|
||||
**AHORA:**
|
||||
- `browser.browserAction` - Botón estándar en la barra
|
||||
- Sin menú en Tools (no disponible en WebExtensions)
|
||||
|
||||
## Estructura de archivos
|
||||
|
||||
### Archivos nuevos
|
||||
- `manifest.json` - Manifiesto WebExtensions
|
||||
- `background.js` - Script de fondo
|
||||
- `content/db-webext.js` - Wrapper de base de datos moderno
|
||||
|
||||
### Archivos modificados
|
||||
- `content/ca-archive.html` - Rutas relativas, navegación por hash
|
||||
- `content/ca-archive.js` - Sin Components, carga dinámica de módulos
|
||||
|
||||
### Archivos obsoletos (ya no se usan)
|
||||
- `install.rdf` - Reemplazado por manifest.json
|
||||
- `chrome.manifest` - Ya no necesario
|
||||
- `bootstrap.js` - Reemplazado por background.js
|
||||
- `update.xml` - Actualizaciones ahora vía Firefox/Chrome stores
|
||||
|
||||
## Compatibilidad
|
||||
|
||||
### Navegadores soportados
|
||||
|
||||
| Navegador | Versión mínima | Notas |
|
||||
|-----------|----------------|-------|
|
||||
| Firefox | 57+ (Quantum) | Soporte completo |
|
||||
| Chrome | 80+ | Requiere manifest V2 |
|
||||
| Edge (Chromium) | 80+ | Compatible con Chrome |
|
||||
| Brave | 1.20+ | Compatible con Chrome |
|
||||
| Vivaldi | 3.0+ | Compatible con Chrome |
|
||||
|
||||
### Navegadores NO soportados
|
||||
|
||||
Los siguientes navegadores que usaban la versión legacy ya no son compatibles con la versión WebExtensions:
|
||||
|
||||
- Firefox ESR 45-52
|
||||
- Firefox 45-56
|
||||
- Pale Moon
|
||||
- Basilisk
|
||||
- Waterfox Classic (pre-Current)
|
||||
- SeaMonkey
|
||||
|
||||
**Nota:** Para estos navegadores, seguir usando la versión 2.x legacy.
|
||||
|
||||
## Instalación
|
||||
|
||||
### Firefox
|
||||
|
||||
1. **Desde archivo local:**
|
||||
```bash
|
||||
# Empaquetar la extensión
|
||||
cd /home/ale/projects/firefox/ca-archive
|
||||
zip -r ca-archive-3.0.zip * -x ".*" -x "*.md" -x "update.xml" -x "install.rdf" -x "chrome.manifest" -x "bootstrap.js"
|
||||
```
|
||||
|
||||
2. En Firefox, ir a `about:debugging` > Este Firefox > Cargar extensión temporal
|
||||
3. Seleccionar el archivo `manifest.json` o el archivo `.zip`
|
||||
|
||||
### Chrome/Edge/Brave
|
||||
|
||||
1. Ir a `chrome://extensions/`
|
||||
2. Activar "Modo de desarrollador"
|
||||
3. Click en "Cargar extensión sin empaquetar"
|
||||
4. Seleccionar la carpeta del proyecto
|
||||
|
||||
## Desarrollo
|
||||
|
||||
### Dependencias
|
||||
|
||||
La extensión requiere `sql.js` para el acceso a la base de datos SQLite:
|
||||
|
||||
```html
|
||||
<!-- Cargado automáticamente desde CDN en db-webext.js -->
|
||||
<script src="https://cdnjs.cloudflare.com/ajax/libs/sql.js/1.8.0/sql-wasm.js"></script>
|
||||
```
|
||||
|
||||
**Para producción:** Descargar sql.js localmente y actualizar las rutas en `db-webext.js`.
|
||||
|
||||
### Debugging
|
||||
|
||||
**Firefox:**
|
||||
- `about:debugging` > Inspeccionar
|
||||
- Console del navegador: `Ctrl+Shift+J`
|
||||
|
||||
**Chrome:**
|
||||
- `chrome://extensions/` > Detalles > Inspeccionar vistas: background page
|
||||
- DevTools: `F12`
|
||||
|
||||
### Testing
|
||||
|
||||
1. Abrir la extensión
|
||||
2. Verificar que la base de datos se carga correctamente
|
||||
3. Probar navegación: listados, búsquedas, detalles de addons
|
||||
4. Verificar que las descargas funcionan
|
||||
|
||||
## Limitaciones conocidas
|
||||
|
||||
### WebExtensions vs Legacy
|
||||
|
||||
1. **Multi-proceso (e10s):** Ahora sólo funciona con e10s activado
|
||||
2. **Protocolo personalizado:** Ya no disponible, usa rutas de extensión
|
||||
3. **Modificación de AMO pages:** No puede inyectar hints en addons.mozilla.org
|
||||
4. **Barra de herramientas:** Botón en ubicación fija, no personalizable
|
||||
5. **Storage:** Base de datos limitada por cuota de storage del navegador
|
||||
|
||||
### Tamaño de base de datos
|
||||
|
||||
Chrome/Firefox tienen límites de storage:
|
||||
- Chrome: ~10MB en `storage.local` (puede ampliarse con `unlimitedStorage`)
|
||||
- Firefox: Sin límite práctico en `storage.local`
|
||||
|
||||
Si la base de datos es muy grande (>10MB), considerar:
|
||||
1. Agregar permiso `unlimitedStorage` en manifest.json
|
||||
2. Usar chunks/compresión
|
||||
3. Almacenar en IndexedDB
|
||||
|
||||
## Migración de datos de usuario
|
||||
|
||||
La nueva versión NO migra automáticamente datos de la versión legacy porque:
|
||||
|
||||
1. Las APIs de storage son completamente diferentes
|
||||
2. La base de datos se descarga nueva en cada instalación
|
||||
3. No hay configuraciones de usuario persistentes
|
||||
|
||||
## Próximos pasos
|
||||
|
||||
### Para publicar en stores
|
||||
|
||||
1. **Firefox Add-ons (AMO):**
|
||||
- Crear cuenta en addons.mozilla.org
|
||||
- Subir archivo .zip
|
||||
- Esperar revisión
|
||||
|
||||
2. **Chrome Web Store:**
|
||||
- Crear cuenta de desarrollador ($5 USD único)
|
||||
- Subir archivo .zip
|
||||
- Completar listing
|
||||
|
||||
### Mejoras futuras
|
||||
|
||||
- [ ] Migrar a Manifest V3 (cuando Firefox tenga mejor soporte)
|
||||
- [ ] Offline-first: cachear más contenido
|
||||
- [ ] Sincronización de favoritos/bookmarks
|
||||
- [ ] Dark mode
|
||||
- [ ] Búsqueda mejorada con índices
|
||||
|
||||
## Soporte
|
||||
|
||||
- GitHub: https://github.com/JustOff/ca-archive/
|
||||
- Issues: https://github.com/JustOff/ca-archive/issues
|
||||
|
||||
## Licencia
|
||||
|
||||
La extensión continúa bajo Mozilla Public License 2.0 (MPL-2.0).
|
||||
Referencia en una nueva incidencia
Block a user