Vai al contenuto principale

Introduzione

Prima di immergerti nello sviluppo, ci auguriamo che tu comprenda i seguenti aspetti:
  • Ufficialmente Overleaf viene sviluppato in un repository interno, mentre la community edition è pubblicata in overleaf/overleaf. Un copybot si occupa di sincronizzare il codice tra il repository interno e quello pubblico.
  • Ayaka-notes/overleaf-pro è un fork della community edition di Overleaf. Speriamo che questo progetto possa durare a lungo, quindi ti chiediamo di seguire le regole prima di contribuire.

Regole per i commit

  • Non apportare modifiche estese al codice Overleaf esistente. Concentra il più possibile le funzionalità nella cartella services/web/modules. Questo ridurrà al minimo il nostro carico di lavoro quando in seguito dovremo unire e aggiornare il codice.
  • Il vibe coding è davvero un approccio molto comodo, ma può facilmente creare disordine nel progetto, rendendolo in seguito impossibile da mantenere: usalo quindi con cautela.
  • Riutilizza le chiavi di traduzione esistenti ogni volta che è possibile. Se serve davvero una nuova chiave, aggiungila in services/web/locales/locales_patches/added/ per tutte le lingue contemporaneamente, vedi Aggiornare le traduzioni i18n.
  • Evita di introdurre variabili d’ambiente se non strettamente necessario. Se servono, assicurati che siano il più possibile coerenti con quelle dell’Overleaf Toolkit o di docs.overleaf.com.

Regole per i branch

Per lo sviluppo di overleaf-pro usiamo i seguenti branch:
  • main: questo branch viene usato solo per la sincronizzazione del codice upstream, quindi NON eseguire commit di modifiche esterne. In questo branch impostiamo alcuni tag come ce-v[X.x.x], che indicano la corrispondenza con la versione v[X.x.x] della Community Edition ufficiale di Overleaf. Nota: questi tag sono immutabili!
  • server-pro: questo è il branch predefinito per lo sviluppo quotidiano.
  • feat-X: questo branch viene usato per sviluppare una funzionalità specifica, ad esempio feat-gitea-sync.
  • release-vX.Y.Z: il branch dedicato al rilascio, in cui applichiamo eventuali hotfix prima della release. Anche le patch release hanno un proprio branch, ad esempio release-v6.3.1. Il commit rilasciato viene taggato pro-vX.Y.Z su questo branch.

Regole dei branch per Overleaf Pro

GitHub Action

GitHub Action si occupa della CI/CD automatica. Non è necessario compilare le immagini sulla propria macchina: ogni immagine qui sotto viene compilata da un workflow, e quelle con avvio manuale possono essere compilate con un clic.
  • Le immagini di sviluppo contengono ciascuna un microservizio (web, webpack, clsi, …) per linux/amd64 e linux/arm64. La configurazione di Codespace le scarica tramite develop/docker-compose.image.yml invece di eseguire bin/build.
  • Le immagini operative sono immagini complete a container singolo (come sharelatex/sharelatex) per testare una modifica end to end. ops:latest si aggiorna solo con i push su server-pro; una PR riceve solo un tag con data e ora. Queste immagini vengono conservate per 7 giorni e servono solo per i test.
  • Le immagini di rilascio sono quelle che gli utenti distribuiscono. La versione deriva dal nome del branch, quindi release-v6.3.0 pubblica overleaf-pro:6.3.0.
1

Eseguire manualmente un workflow

Apri la scheda Actions, scegli il workflow a sinistra, fai clic su Run workflow e conferma. Build Operations Image offre anche l’opzione Build without cache per quando un layer in cache è obsoleto.
2

Compilare nel proprio fork

Gli stessi workflow funzionano in un fork: abilita Actions nel tuo fork, quindi eseguili dalla relativa scheda Actions. Le immagini vengono inviate a ghcr.io/<your-name>/overleaf-pro/... con il GITHUB_TOKEN integrato, quindi non servono secret. Sync Upstream Code e la pulizia delle vecchie immagini vengono eseguiti solo in ayaka-notes.Build Release Image richiede un branch release-v* nel tuo fork.
Per verificare da quale commit è stata compilata un’immagine: il tag di un’immagine operativa termina con l’hash breve del commit, mentre un’immagine di rilascio lo riporta nell’etichetta com.overleaf.pro.revision (vedi docker inspect nelle domande e risposte qui sotto).

Domande e risposte

Prima di tutto devi scaricare l’immagine Docker ed eseguire il seguente comando per ispezionarne le etichette:
bash
Poi puoi verificare se il commit (b0d05c0) è presente nel branch master upstream.
È un comportamento previsto. La release 6.0.1 è una patch minore costruita sopra l’immagine 6.0.0. Le modifiche vengono applicate applicando patch all’immagine 6.0.0 esistente, anziché ricostruire l’immagine da un nuovo commit. Per questo l’hash del commit all’interno dell’immagine è identico tra 6.0.0 e 6.0.1.Per informazioni dettagliate, consulta hotfix.
Ultima modifica il 20 novembre 2026