Desenvolupar

Anuncieu sempre les funcions en què voleu treballar creant un tiquet o comentant-ne un d’existent, abans de començar a treballar-hi, i anunciar clarament a la comunitat que esteu començant a treballar-hi. Això és per evitar que diverses persones treballin en el mateix i entrin en conflicte.

Les «Pull Request» s’han de fer a la branca main.

Requisits previs per compilar aquest connector

És molt recomanable estar familiaritzat/da amb els conceptes següents:

• Git
• NodeJS
• NPM
• Typescript

Per construir el connector cal que tingueu instal·lats els paquets següents:

• git
• npm (>=8.x)
• nodejs (>=14.x)
• build-essential
• coreutils
• wget
• reuse

Tingueu en compte que aquest connector necessita una AppImage del servidor XMPP Prosody. Aquesta AppImage la proporciona el projecte Prosody AppImage. L’script build-prosody.sh baixa els binaris connectats a aquest repositori remot i verifica que les sumes de verificació sha256 siguin correctes.

Desenvolupar

Cloneu el repositori, construïu el connector i creeu la vostra branca de funcionalitat:

# Clonar el repositori. No oblideu el --recursive, per clonar els submòduls.
git clone https://github.com/JohnXLivingston/peertube-plugin-livechat.git --recursive

cd peertube-plugin-livechat

# Instal·lar les dependències NPM i compilar el connector per primera vegada:
npm install

# Compilar el connector després d'una modificació:
npm run build

# Si teniu una bifurcació del repositori, afegiu-la de manera remota (exemple):
git remote add me git@github.com:EL_MEU_COMPTE_GITHUB/peertube-plugin-livechat.git

# Creeu una sucursal local per als vostres desenvolupaments i col·loqueu-vos-hi (exemple):
git checkout meu_desenvolupament # Nota: si hi ha associat un tiquet, utilitzeu el nom fix_1234 (on 1234 és el número de tiquet)
# Per proposar les vostres modificacions envieu la vostra branca al vostre repositori (exemple):
git push --set-upstream me meu_desenvolupament
# A continuació, aneu al vostre repositori github amb el vostre navegador web per proposar la «Pull Request» (vegeu les instruccions addicionals a continuació)

Quan estigueu preparat/da per mostrar el vostre codi i demanar comentaris, envieu una «Pull Request» esborrany. Quan estigueu preparat/da per a una revisió del codi abans de la fusió, envieu una «Pull Request». En tots els casos, enllaceu la vostra PR amb el tiquet en qüestió mitjançant la sintaxi de GitHub: «fixes #issue_NombreTiquet».

El codi del «front-end» es troba a la carpeta client. El codi del «back-end» a server. Hi ha codi compartit entre els dos a shared.

Per a instruccions genèriques sobre el desenvolupament de connectors (construcció, instal·lació, etc.), consulteu la documentació de Peertube.

Podeu construir el connector amb informació de depuració addicional mitjançant:

NODE_ENV=dev npm run build

Aquest connector compleix amb l’estàndard REUSE: utilitza capçaleres SPDX per identificar la informació de llicència del seu codi font. Més informació al lloc web REUSE. Podeu utilitzar l’eina de línia d’ordres reuse per ajudar-vos a actualitzar les capçaleres. L’ordre npm run lint utilitzarà l’ordre reuse per comprovar el compliment. No oblideu afegir la vostra informació de copyright a les capçaleres SPDX quan canvieu el codi.

ESBuild vs Typescript

Aquest connector utilitza ESBuild per compilar el codi del «front-end», com el connector oficial peertube-plugin-quickstart. ESBuild pot gestionar Typescript, però no verifica els tipus (vegeu documentació d’ESBuild). És per això que primer compilem Typescript amb l’opció -noEmit, només per comprovar els tipus (check:client:ts al fitxer package.json). Aleshores, si tot està bé, iniciem ESBuild per generar el javascript compilat.

Mode de depuració

Hi ha un mode de depuració per al connector, que escurçarà el temps necessari per a determinades accions. Per exemple, rotarà els registres cada dos minuts, en lloc de cada dia. Això facilita la prova de determinades accions, per a les quals normalment hauríeu d’esperar hores o dies.

Per activar aquest mode només cal que creeu un fitxer /var/www/peertube/storage/plugins/data/peertube-plugin-livechat/debug_mode (adaptant /var/www/peertube/storage/ a la vostra instal·lació si escau) .

La mera existència d’aquest fitxer és suficient per activar el mode de depuració. Per assegurar-vos que es té en compte, podeu reiniciar la vostra instància de Peertube.

Aquest fitxer també pot contenir JSON que pot activar altres opcions més avançades. Per obtenir-ne una llista, podeu consultar el codi a server/lib/debug.ts. Reinicieu Peertube després de cada modificació del seu contingut.

Reiniciar Prosody

Per reiniciar Prosody quan el mode de depuració estigui activat, podeu cridar l’API http://la_vostra_instancia.cat/plugins/livechat/router/api/restart_prosody. Aquesta crida no necessita autenticació. Es pot fer des d’una línia d’ordres, per exemple amb curl http://la_vostra_instancia.cat/plugins/livechat/router/api/restart_prosody.

Depurador de Prosody

És possible connectar l’AppImage Prosody a un depurador remot mitjançant MobDebug.

Per fer-ho, col·loqueu MobDebug en una carpeta accessible per l’usuari peertube. A continuació afegiu això al fitxer debug_mode del connector:

{
  "debug_prosody": {
    "debugger_path": "/el_cami_a_mobdebug/src",
    "host": "localhost",
    "port": "8172"
  }
}

host i port són opcionals. debugger_path ha d’apuntar a la carpeta on es troba el fitxer .lua de MobDebug.

Reiniciar Peertube.

Inicieu el vostre servidor de depuració.

Perquè Prosody es connecti al depurador, crideu a l’API http://la_vostra_instancia.cat/plugins/livechat/router/api/restart_prosody?debugger=true. Aquesta crida no necessita autenticació. Es pot fer des d’una línia d’ordres, per exemple amb curl http://la_vostra_instancia.cat/plugins/livechat/router/api/restart_prosody?debugger=true. Fins i tot podeu configurar el vostre servidor de depuració per executar aquesta ordre automàticament.

Aleshores Prosody es reiniciarà, connectant-se al depurador.

Entorn de desenvolupament ràpid mitjançant Docker

Hi ha un tutorial, en francès, disponible al [fòrum Peertube](https://framacolibri.org/t/tutoriel-creer-un-environnement-de-developpement-de-plugin-peertube-rapidement-en-utilisant-docker-et-qui -allows-to-test-the-federation/17631) que explica com configurar ràpidament un entorn de desenvolupament amb Docker.

S’ha creat un repositori basat en aquest tutorial: pt-plugin-dev.

Nota: per algun motiu desconegut Prosody no pot resoldre les adreces DNS dels contenidors quan s’utilitza la biblioteca lua-unbound. Per evitar-ho hi ha una «nyapa»: només cal que creeu un fitxer /data/plugins/data/peertube-plugin-livechat/no_lua_unbound als vostres volums docker i reinicieu-los.

Reconstruir i instal·lar el connector ràpidament

Quan feu canvis no cal que reconstruïu tot el projecte i torneu a instal·lar el connector al vostre entorn de desenvolupament; podeu crear només la part modificada (per exemple, si només heu modificat els fitxers del client: npm run build:client). Trobareu la llista dels scripts de compilació disponibles al fitxer package.json.

Quan el connector ja està instal·lat a la vostra instància de desenvolupament i si no heu modificat cap dependència, podeu instal·lar ràpidament el vostre treball seguint els passos següents:

• reconstruir les parts necessàries del connector (client, estils, …),
• sobreescriure el contingut de data/plugins/node_modules/peertube-plugin-livechat/dist/ de la vostra instància de desenvolupament amb el contingut de la carpeta dist del connector,
• canviar recursivament el propietari dels fitxers plugins/node_modules/peertube-plugin-livechat/dist/ al vostre usuari peertube,
• reiniciar la vostra instància.

Proves de rendiment

El repositori livechat-perf-test conté algunes eines per realitzar proves de rendiment. Es poden utilitzar per avaluar millores del codi font o trobar colls d’ampolla.