docs: la guia escrita como notas, sin adornos
This commit is contained in:
SITO
parent
abae8132a4
commit
5bce7d38ed
3 changed files with 158 additions and 198 deletions
|
|
@ -1,218 +1,180 @@
|
|||
# Guía de desarrollo de OASIS_MOBILE
|
||||
# Guía de desarrollo
|
||||
|
||||
**Léela antes de tocar nada.** Esta rama vive encima de Oasis, que desarrolla
|
||||
epsylon (el dev) y que saca una versión casi cada día. Todo lo que añadimos tiene
|
||||
que sobrevivir a la siguiente versión sin reescribirlo. Esta guía dice qué se puede
|
||||
tocar, qué no y cómo hacer cada tipo de cambio.
|
||||
Notas para quien vaya a meter mano en la rama del móvil. Leedlas antes de empezar,
|
||||
que nos ahorramos disgustos.
|
||||
|
||||
Las cifras y el razonamiento están en
|
||||
[docs/FRONTERA_UPSTREAM.md](docs/FRONTERA_UPSTREAM.md). Aquí solo van las reglas.
|
||||
Esta rama va encima de Oasis, que es de epsylon. Él saca versión casi cada día
|
||||
(39 entre la 1.0.1 y la 1.3.3, en siete semanas) y cada versión llega en un solo
|
||||
commit. Si metemos cosas en sus ficheros, en cada integración hay que volver a
|
||||
pelearse con ellas. Por eso la idea es sencilla: lo de Oasis lo cambia él; nosotros
|
||||
cambiamos cómo se ve y se usa en el móvil, y lo hacemos en ficheros nuestros.
|
||||
|
||||
---
|
||||
Los números y de dónde salen están en `docs/FRONTERA_UPSTREAM.md`.
|
||||
|
||||
## 1. La regla de oro
|
||||
|
||||
> **Oasis lo cambia el dev. Nosotros cambiamos cómo se ve en el móvil.**
|
||||
>
|
||||
> Lo que la rama añade va en **ficheros nuestros**. En un fichero del dev, como mucho,
|
||||
> **una línea que llama a un fichero nuestro**, y solo en el móvil.
|
||||
## Lo que no se toca
|
||||
|
||||
¿Por qué? Entre la 1.0.1 y la 1.3.3 (siete semanas) el dev publicó 39 versiones, cada
|
||||
una en un único commit. `backend.js` cambió en 34 de ellas, `main_views.js` en 31,
|
||||
las traducciones en 31. Cada línea nuestra en esos ficheros es un conflicto casi
|
||||
seguro en la próxima integración. Y si tocamos cómo se publica o se cuenta algo en la
|
||||
red, nuestro móvil deja de entenderse con los demás nodos.
|
||||
- `src/backend/backend.js`. Cambia en 34 de cada 39 versiones. Ni rutas nuevas, ni
|
||||
middleware, ni envolver funciones suyas como `checkMod`.
|
||||
- La cadena de middleware del final de `backend.js`. Crece en cada versión.
|
||||
- Los modelos de `src/models/`, salvo los nuestros (`karvan_model.js`,
|
||||
`fork_workflows.js`). Ahí se decide qué se publica en la red y cómo se cuenta.
|
||||
Si lo cambiamos, nuestro móvil cuenta distinto que el escritorio de al lado. Un
|
||||
ejemplo real: quien crea una votación no puede votar en ella. No nos gusta, pero
|
||||
es una regla del modelo, así que se explica en pantalla y punto.
|
||||
- `src/server/` (arranque de SSB, `ssb_config.js`, `package.json`).
|
||||
- `src/backend/request_guards.js`, que lleva la CSP. Nada de `style=""` ni de
|
||||
`<script>` en la página.
|
||||
- Las traducciones del dev, `translations/oasis_*.js`. Se reescriben casi en cada
|
||||
versión.
|
||||
- `styles/style.css` y `styles/mobile.css`.
|
||||
- Los temas del dev: Dark, Clear, Purple, Matrix y también `OasisMobile.css`, que
|
||||
aunque parezca nuestro es suyo (lo toca en 21 de 39 versiones).
|
||||
|
||||
---
|
||||
|
||||
## 2. El semáforo
|
||||
## Las vistas del dev: una línea y ya
|
||||
|
||||
### ROJO: no se toca
|
||||
|
||||
| Qué | Dónde | Por qué |
|
||||
|---|---|---|
|
||||
| El backend del dev | `src/backend/backend.js` | Cambia en 34/39 versiones. Rutas, middleware, todo. |
|
||||
| La cadena de middleware | el array `middleware` al final de `backend.js` | Crece en cada versión (contexto por petición, idioma, CSP...). |
|
||||
| Los modelos del dev | `src/models/*` salvo los nuestros (ver verde) | Definen qué se publica en el log SSB y cómo se cuenta. Cambiarlos rompe la red. |
|
||||
| El arranque de SSB | `src/server/*` (`SSB_server.js`, `ssb_config.js`, `package.json`) | Dependencias y conexión con la red. |
|
||||
| La política de seguridad | `src/backend/request_guards.js` | La CSP: sin `style=""` ni `<script>` en línea. Así se queda. |
|
||||
| Las traducciones del dev | `src/client/assets/translations/oasis_*.js` | Se reescriben en 31/39 versiones. |
|
||||
| Las hojas del dev | `styles/style.css`, `styles/mobile.css` | Cambian en 32/39 y 10/39. |
|
||||
| Los temas del dev | `themes/Dark-SNH.css`, `Clear-SNH.css`, `Purple-SNH.css`, `Matrix-SNH.css`, **`OasisMobile.css`** | `OasisMobile.css` es **del dev** (21/39), no nuestro. |
|
||||
|
||||
Ejemplos de lo que **no** se hace:
|
||||
- Cambiar una regla de un modelo, aunque parezca mala. "Quien crea una votación no
|
||||
vota" está en `votes_model.js`: se explica en pantalla, no se cambia.
|
||||
- Añadir una ruta o un middleware a `backend.js`.
|
||||
- Envolver o reescribir una función del backend (`checkMod`, `getConfig`...).
|
||||
- Editar `oasis_es.js` para cambiar un texto.
|
||||
- Meter estilos en línea o `<script>` en una vista.
|
||||
|
||||
### ÁMBAR: una línea de enganche y nada más
|
||||
|
||||
Las **vistas del dev** (`src/views/*_view.js`, `main_views.js`). Se reescriben a
|
||||
menudo (`tribes_view.js` en 23/39, `main_views.js` en 31/39), así que:
|
||||
|
||||
- La lógica va en `src/views/mobile_ui.js` (o en otro `mobile_*.js` nuestro).
|
||||
- En la vista del dev queda **una llamada**, siempre detrás de la bandera:
|
||||
`src/views/*_view.js` y `main_views.js` son del dev y las reescribe a menudo
|
||||
(`tribes_view.js` en 23 versiones, `main_views.js` en 31). Si en una pantalla suya
|
||||
hace falta otro HTML en el móvil, el código va en `src/views/mobile_ui.js` y en la
|
||||
vista solo queda la llamada:
|
||||
|
||||
```js
|
||||
// en tribes_view.js (del dev)
|
||||
const mobileUi = require('./mobile_ui');
|
||||
...
|
||||
// ...
|
||||
if (mobileUi.isMobile()) return mobileUi.tribeTabs(tribe, section, sections);
|
||||
```
|
||||
|
||||
- Si el dev reescribe la vista, se vuelve a poner esa línea. No hay que reconstruir
|
||||
una función entera.
|
||||
- En escritorio (sin `OASIS_MOBILE`) la vista del dev funciona igual que en el
|
||||
original.
|
||||
Cuando el dev reescribe la vista, se vuelve a poner esa línea y listo. En escritorio
|
||||
no cambia nada porque la bandera `OASIS_MOBILE` solo la pone `main.js` en el móvil.
|
||||
|
||||
Enganches que hay hoy: `main_views.js` (6), `tribes_view.js` (6), `vote_view.js` (4),
|
||||
`settings_view.js` (3), `welcome_view.js` (3). Para encontrarlos:
|
||||
`grep -n mobileUi src/views/*.js`.
|
||||
Ahora mismo hay enganches en `main_views.js`, `tribes_view.js`, `vote_view.js`,
|
||||
`settings_view.js` y `welcome_view.js`. Para verlos: `grep -n mobileUi src/views/*.js`.
|
||||
|
||||
### VERDE: nuestro, se toca libremente
|
||||
|
||||
| Para qué | Fichero |
|
||||
|---|---|
|
||||
| Aspecto de los dos skins de móvil (márgenes, letra, botones, piezas nuevas) | `src/client/assets/styles/mobile_ux.css` |
|
||||
| Colores y formas del skin Acampada | `src/client/assets/themes/Acampada.css`, `styles/hive_acampada.css` |
|
||||
| Estilos de Karvan | `styles/karvan.css` |
|
||||
| Piezas de interfaz que se enchufan en vistas del dev | `src/views/mobile_ui.js` |
|
||||
| Pantallas enteras propias | `src/views/mobile_modules_view.js`, `karvan_view.js`, `identities_view.js` |
|
||||
| Lanzador, barra de abajo, barra de arriba | `src/views/hive_views.js` |
|
||||
| Iconos | `src/views/mobile_icons.js` |
|
||||
| Rutas propias y retoques a respuestas del dev | `src/backend/karvan_routes.js` (el router propio) |
|
||||
| Workflows propios | `src/models/fork_workflows.js` |
|
||||
| Modelos propios | `src/models/karvan_model.js` |
|
||||
| JavaScript de cliente propio | `src/client/public/js/karvan.js` |
|
||||
| Textos nuevos | `src/client/assets/translations/i18n_fork.js` |
|
||||
| Imágenes propias | `src/client/assets/images/ux-*.svg` |
|
||||
| La app Android | `android/` |
|
||||
## Lo que es nuestro
|
||||
|
||||
---
|
||||
Aquí se puede hacer lo que haga falta.
|
||||
|
||||
## 3. Cómo se hace cada cosa
|
||||
- `src/client/assets/styles/mobile_ux.css`: márgenes, letra, botones y todas las
|
||||
piezas nuevas. Vale para los dos skins de móvil.
|
||||
- `src/client/assets/themes/Acampada.css` y `styles/hive_acampada.css`: el skin
|
||||
Acampada.
|
||||
- `styles/karvan.css`, `src/views/karvan_view.js`, `src/models/karvan_model.js`,
|
||||
`src/client/public/js/karvan.js`: Karvan entero.
|
||||
- `src/views/mobile_ui.js`: lo que se enchufa en vistas del dev.
|
||||
- `src/views/mobile_modules_view.js`, `identities_view.js`: pantallas propias.
|
||||
- `src/views/hive_views.js`: lanzador y barras de arriba y abajo.
|
||||
- `src/views/mobile_icons.js`: los iconos.
|
||||
- `src/backend/karvan_routes.js`: nuestro router. Va justo delante del del dev.
|
||||
- `src/models/fork_workflows.js`: nuestros workflows.
|
||||
- `src/client/assets/translations/i18n_fork.js`: nuestros textos.
|
||||
- `src/client/assets/images/ux-*.svg`: nuestras imágenes.
|
||||
- `android/`.
|
||||
|
||||
### Cambiar cómo se ve algo
|
||||
1. Busca la clase en el HTML (servidor local + inspector, ver sección 6).
|
||||
2. Escribe la regla en `mobile_ux.css`. Los colores, siempre con los tokens `--ux-*`
|
||||
(`--ux-bg`, `--ux-fg`, `--ux-accent`, `--ux-muted`, `--ux-line`, `--ux-danger`...):
|
||||
así sale bien en Acampada y en OasisMobile.
|
||||
3. Si no gana: `mobile.css` y `Acampada.css` usan `!important` y selectores largos.
|
||||
Sube la especificidad (`.main-column div.x`, `label.x input.y[type="checkbox"]`) y
|
||||
pon `!important`. Ojo: `Acampada.css` quita el borde a **todos** los `div`; para
|
||||
ponerle borde a uno, `.main-column div.mi-clase`.
|
||||
4. Letra: **Anton solo en títulos y en el botón principal negro** (`.create-button`).
|
||||
Todo lo demás, en la letra del sistema en negrita.
|
||||
5. Márgenes: uno solo, de 14 px a cada lado. No añadas rellenos a contenedores
|
||||
intermedios.
|
||||
|
||||
### Cambiar el HTML de una pantalla del dev
|
||||
1. Función nueva en `mobile_ui.js`, que reciba lo que necesite como parámetro.
|
||||
2. Una línea en la vista del dev: `mobileUi.isMobile() ? mobileUi.miPieza(...) : lo_de_antes`.
|
||||
3. Los textos, por `i18n` (ver "Textos").
|
||||
## Cómo hacer cada cosa
|
||||
|
||||
### Una pantalla entera nueva, o una ruta nueva
|
||||
En el router propio, `src/backend/karvan_routes.js`. Va justo **antes** del router
|
||||
del dev en la cadena: lo que no atiende pasa al del dev con `next()`.
|
||||
Cambiar cómo se ve algo. Se busca la clase en el HTML (servidor local e inspector) y
|
||||
se escribe la regla en `mobile_ux.css`. Para los colores usad las variables `--ux-*`
|
||||
(`--ux-bg`, `--ux-fg`, `--ux-accent`, `--ux-muted`, `--ux-line`, `--ux-danger`), que
|
||||
tiran de Acampada si está y si no de la paleta de OasisMobile. Si la regla no gana,
|
||||
es que `mobile.css` o `Acampada.css` mandan con `!important` y selectores largos:
|
||||
hay que subir la especificidad y poner `!important` también. Ojo con una trampa:
|
||||
`Acampada.css` quita el borde a todos los `div`, así que para ponérselo a uno hace
|
||||
falta `.main-column div.la-clase`.
|
||||
|
||||
Letra: Anton para títulos y para el botón negro principal de cada pantalla
|
||||
(`.create-button`). Lo demás, letra del sistema en negrita.
|
||||
|
||||
Márgenes: 14 px a cada lado y ya. Los contenedores de en medio sin relleno, que
|
||||
antes se iban sumando y una ficha perdía 74 px por lado.
|
||||
|
||||
Cambiar el HTML de una pantalla del dev. Función en `mobile_ui.js` y una línea en la
|
||||
vista, como arriba.
|
||||
|
||||
Una pantalla o una ruta nueva. En `karvan_routes.js`. Lo que no atiende nuestro
|
||||
router pasa al del dev con `next()`:
|
||||
|
||||
```js
|
||||
.get('/modules', async (ctx, next) => {
|
||||
if (!isMobile()) return next(); // en escritorio, la del dev
|
||||
ctx.body = mobileModulesView({ ... }); // en el movil, la nuestra
|
||||
if (!isMobile()) return next(); // escritorio: la del dev
|
||||
ctx.body = mobileModulesView({ ... });
|
||||
})
|
||||
```
|
||||
|
||||
### Retocar lo que responde el dev, sin editarlo
|
||||
El envoltorio `wrapUpstream` de `karvan_routes.js` deja actuar al dev y después mira
|
||||
la respuesta. Así se sabe a qué sección apagada se quería entrar (el dev solo
|
||||
redirige a `/modules`) o se añade `?saved=1` tras guardar. Este es el sitio para eso,
|
||||
nunca `backend.js`.
|
||||
Retocar lo que contesta el dev. También en `karvan_routes.js`, en `wrapUpstream`: deja
|
||||
que el dev conteste y luego mira la respuesta. Así sabemos a qué sección apagada se
|
||||
quería entrar (el dev solo manda a `/modules`) o añadimos `?saved=1` al guardar.
|
||||
|
||||
### Textos
|
||||
- Siempre en `i18n_fork.js`, **en los 11 idiomas** (en, es, fr, eu, de, it, pt, zh,
|
||||
ar, hi, ru).
|
||||
- Comprueba que la clave no existe ya en `oasis_en.js`: si existe, se pisaría también
|
||||
en escritorio.
|
||||
- En el código, siempre con texto de reserva en inglés: `i18n.miClave || 'My text'`.
|
||||
Textos. En `i18n_fork.js` y en los 11 idiomas (en, es, fr, eu, de, it, pt, zh, ar,
|
||||
hi, ru). Antes, mirad que la clave no exista ya en `oasis_en.js`, porque si existe la
|
||||
estaríais cambiando también en escritorio. En el código siempre con texto de reserva:
|
||||
`i18n.miClave || 'My text'`.
|
||||
|
||||
### Un workflow nuevo
|
||||
En `fork_workflows.js`. Se registra empujándolo a los arrays que exporta el modelo
|
||||
del dev. No se edita `workflows_model.js` ni se redefine un workflow del dev.
|
||||
Un workflow. En `fork_workflows.js`, que lo mete en las listas que exporta el modelo
|
||||
del dev. No se toca `workflows_model.js`.
|
||||
|
||||
### Un icono
|
||||
En `mobile_icons.js`: trazo de 2 px en rejilla de 24, `currentColor`. La clave es la
|
||||
ruta (`/tribes` → `tribes`).
|
||||
Un icono. En `mobile_icons.js`, trazo de 2 px sobre rejilla de 24 y `currentColor`. El
|
||||
nombre es el de la ruta: `/tribes` es `tribes`.
|
||||
|
||||
### Algo que solo pasa en el móvil
|
||||
Siempre detrás de `process.env.OASIS_MOBILE === '1'` (o `mobileUi.isMobile()`).
|
||||
`main.js` la pone; el escritorio no la tiene.
|
||||
|
||||
---
|
||||
## Antes de hacer commit
|
||||
|
||||
## 4. Antes de cada commit
|
||||
- Que `git diff --stat` no toque nada de la lista de lo que no se toca. En las vistas
|
||||
del dev, solo líneas de enganche.
|
||||
- `node --check` en los `.js` que hayáis cambiado.
|
||||
- Arrancar en local y ver que `/activity`, `/tribes`, `/modules`, `/settings`,
|
||||
`/votes`, `/karvan` e `/inbox` cargan.
|
||||
- Mirarlo a 412 px de ancho, y a 360 si es algo ancho.
|
||||
- Los textos nuevos, en los 11 idiomas.
|
||||
- Nada en línea, que la CSP lo bloquea.
|
||||
- Commit en castellano, sin coautorías de herramientas.
|
||||
- Sin claves, contraseñas ni nada de `.ssb`.
|
||||
|
||||
- [ ] `git diff --stat` no toca nada rojo. Si toca una vista del dev, son líneas de
|
||||
enganche, no funciones.
|
||||
- [ ] `node --check` en cada `.js` cambiado.
|
||||
- [ ] El servidor local arranca y responde 200 en `/activity`, `/tribes`, `/modules`,
|
||||
`/settings`, `/votes`, `/karvan`, `/inbox`.
|
||||
- [ ] Mirado a 412 px de ancho (y a 360 si es una pieza ancha).
|
||||
- [ ] Textos nuevos en los 11 idiomas.
|
||||
- [ ] Nada en línea (`style=""`, `<script>`): la CSP lo bloquea.
|
||||
- [ ] Commit en castellano, sin rastro de herramientas ni coautorías automáticas.
|
||||
- [ ] Ninguna clave, contraseña ni `.ssb` en el commit.
|
||||
|
||||
---
|
||||
## Cuando sale versión nueva del dev
|
||||
|
||||
## 5. Cuando sale una versión nueva del dev
|
||||
1. Lo suyo se coge tal cual.
|
||||
2. En sus vistas se vuelven a poner los enganches. El `grep -n mobileUi` sobre la
|
||||
versión anterior de la rama dice dónde iban.
|
||||
3. Se repite la medición de `docs/FRONTERA_UPSTREAM.md`: qué ha tocado y si ha
|
||||
desaparecido alguna clase que usen nuestras hojas.
|
||||
4. Se repasan a 412 px las pantallas de la lista de arriba.
|
||||
5. Se compila la APK con la oficial de esa misma versión como base
|
||||
(`android/scripts/release.sh` con `OASIS_APK_BASE`).
|
||||
|
||||
1. Coge su código tal cual para todo lo rojo.
|
||||
2. En las vistas del dev, vuelve a poner los enganches (`grep -n mobileUi`
|
||||
en la versión anterior de la rama te dice dónde estaban).
|
||||
3. Repite la medición de [docs/FRONTERA_UPSTREAM.md](docs/FRONTERA_UPSTREAM.md):
|
||||
qué ficheros ha tocado y si ha desaparecido alguna clase de la que tiran nuestras
|
||||
hojas.
|
||||
4. Revisa a 412 px las pantallas de la sección 4.
|
||||
5. Compila la APK con la oficial de **esa misma versión** como base
|
||||
(`android/scripts/release.sh`, variable `OASIS_APK_BASE`).
|
||||
|
||||
---
|
||||
|
||||
## 6. Cómo probar
|
||||
|
||||
**Servidor local** (con una identidad de usar y tirar y la red en pausa):
|
||||
## Probar en local
|
||||
|
||||
```sh
|
||||
HOME=/tmp/oasis-prueba OASIS_NETWORK_PAUSED=1 node main.js
|
||||
# http://localhost:3000, con el inspector del navegador en modo movil, 412x915
|
||||
```
|
||||
|
||||
- `src/server/node_modules` no está en git: hace falta uno (el de la APK base vale).
|
||||
Y en el navegador `http://localhost:3000` con el inspector en modo móvil a 412x915.
|
||||
Va con una identidad de usar y tirar y con la red parada.
|
||||
|
||||
Cosas que pasan:
|
||||
- `src/server/node_modules` no está en git. Sirve el de la APK base.
|
||||
- Si al reiniciar sale "Another Oasis instance is already running", el anterior sigue
|
||||
vivo y estás viendo código viejo: mátalo antes.
|
||||
- Al arrancar se borran `src/configs/banking-eco-history.json` y
|
||||
`fediverse-accounts.json`: `git checkout -- src/configs/` antes de hacer commit.
|
||||
vivo y estáis viendo código viejo. Matadlo primero.
|
||||
- Al arrancar desaparecen `src/configs/banking-eco-history.json` y
|
||||
`fediverse-accounts.json`. Antes del commit, `git checkout -- src/configs/`.
|
||||
|
||||
**En el emulador** (Android Studio, `Pixel_9_API_36`): la APK de depuración deja
|
||||
inspeccionar la WebView con `chrome://inspect` o con
|
||||
`adb forward tcp:9333 localabstract:webview_devtools_remote_<pid>`.
|
||||
En el emulador (`Pixel_9_API_36` de Android Studio), la APK de depuración deja
|
||||
inspeccionar la WebView desde `chrome://inspect`.
|
||||
|
||||
---
|
||||
|
||||
## 7. Deuda que queda (por orden)
|
||||
## Lo que todavía está mal
|
||||
|
||||
Cosas de antes de esta guía que todavía la incumplen. Ver la sección 5 de
|
||||
[docs/FRONTERA_UPSTREAM.md](docs/FRONTERA_UPSTREAM.md).
|
||||
Cosas de antes de estas normas que aún no las cumplen, por orden de lo que más
|
||||
duele:
|
||||
|
||||
1. **`OasisMobile.css`** difiere en 4.873 líneas de la del dev. Hay que devolverle la
|
||||
suya y llevar nuestra maqueta a una hoja propia.
|
||||
2. **21 trozos antiguos en `backend.js`** (14 con la bandera de móvil): exportar copia
|
||||
de seguridad, avatar de la barra de arriba, vídeos, filtro del lanzador... Pasan al
|
||||
router propio.
|
||||
3. **El workflow "activists"** sigue redefinido en `workflows_model.js`: devolver el del
|
||||
dev (ya existe el nuestro, "acampada").
|
||||
4. **Selectores muertos** en `OasisMobile.css` (61), `hive_acampada.css` (29) y
|
||||
`Acampada.css` (5).
|
||||
1. `OasisMobile.css` se parece poco a la del dev: 4.873 líneas distintas. Hay que
|
||||
devolverle la suya y pasar nuestra maqueta a una hoja propia.
|
||||
2. Quedan 21 trozos nuestros en `backend.js` (copia de seguridad, avatar de la barra
|
||||
de arriba, vídeos, filtro del lanzador...). Tienen que irse al router propio.
|
||||
3. El workflow `activists` sigue cambiado en `workflows_model.js`. Hay que dejarlo
|
||||
como el del dev; el nuestro ya es `acampada`.
|
||||
4. Selectores que ya no apuntan a nada: 61 en `OasisMobile.css`, 29 en
|
||||
`hive_acampada.css` y 5 en `Acampada.css`.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue