Saltar al contingut principal

Capítol 14 · Part III · La pràctica

Contribuir a Postext

Com unir-se a la comunitat Postext i contribuir al projecte

Actualitzat 2026-10-196 minenescadefritptzhjaar

En poques paraules

Postext el construeix una comunitat de voluntaris, i qualsevol persona hi pot ajudar. No cal saber programar. També pots ajudar fent proves, escrivint documentació, traduint o compartint el que saps de disseny i d'impremta. Aquesta pàgina explica com treballa l'equip, on fa més falta ajuda i com fer la teva primera aportació. Acaba amb els objectius del projecte a llarg termini.

Construïm junts el motor de composició editorial que el web no ha tingut mai.

Postext és un projecte de codi obert impulsat per la comunitat. Vol resoldre un problema que fa dècades que s'ignora: portar la composició editorial professional al web. És una ambició gran, i una sola persona no hi arriba.

El projecte és jove, però ja no és una pàgina en blanc: el nucli del motor de composició, el format de document i el sistema de configuració ja estan publicats. Tot i això, queden moltes decisions de disseny obertes, i qui s'hi incorpora ara té una influència real sobre el rumb del projecte. Si esperaves un bon moment per unir-t'hi, és aquest.

No cal ser programador per contribuir. Tant si escrius codi com si maquetes publicacions, entens de tipografia, fas proves en diferents navegadors, redactes documentació, tradueixes contingut o simplement tens idees sobre com hauria de funcionar el contingut editorial al web, aquí hi ha un lloc per a tu.

#Per què contribuir

Totes les empreses de desenvolupament editorial del món topen amb el mateix problema: CSS no es va dissenyar per a la maquetació editorial. No té suport natiu per a l'equilibratge de columnes, per evitar òrfenes i vídues, per fer fluir el text al voltant d'obstacles ni per col·locar les notes a peu de pàgina. Cada equip resol aquests problemes des de zero, amb solucions fràgils i fetes a mida que són cares de mantenir i impossibles de compartir.

Postext vol canviar això, no com una eina propietària, sinó com un estàndard obert i compartit: un únic motor de composició d'alta qualitat que editorials, revistes, diaris, plataformes de llibres i equips de desenvolupament de tot el món puguin adoptar i fer servir com a base.

Un estàndard així no el pot construir una sola persona ni una sola empresa. Necessita la mirada de tipògrafs de tradicions diferents, especialistes en PDF, experts en accessibilitat, desenvolupadors que treballin amb escriptures de dreta a esquerra, dissenyadors que maquetin revistes i enginyers que optimitzin el rendiment del renderitzat. Un món editorial tan divers exigeix una comunitat igual de diversa al darrere de l'eina que li dona servei.

#Com treballem

Tota la coordinació es fa a GitHub. No hi ha canals privats, ni llistes de correu tancades, ni decisions preses a porta tancada. Tot és públic, es pot cercar i és obert a la participació.

  • Issues: per informar d'errors, demanar funcionalitats i proposar tasques concretes. Si vols treballar en alguna cosa, comença per aquí.
  • Pull Requests: per a les contribucions de codi. Abans d'escriure codi, obre un issue per discutir l'enfocament.
  • Discussions: per a idees, converses de disseny, preguntes i tot allò que no sigui un error o una tasca concrets. És el lloc per pensar en veu alta.

És una decisió deliberada: quan tot és en un sol lloc, qualsevol persona pot trobar el context de cada decisió, i els col·laboradors nous poden llegir-ne l'historial.

Flux típic de contribucióUna idea comença com a Issue o Discussion, es discuteix, es converteix en un Pull Request que es revisa i finalment es fusiona. Els issues etiquetats com a good first issue són el punt d’entrada per a qui comença.1Issueproblema o idea2Discussionenfocament i disseny3Pull Requestrevisió del codi4Mergea developgood first issuemillor punt d’entrada
De la idea a la fusió: quatre etapes, totes públiques a GitHub.

#Àrees on pots ajudar

El projecte necessita experiència de molts tipus. Aquestes són algunes àrees on les contribucions són especialment valuoses:

#Codi i algorismes

  • Algorismes de composició tipogràfica: el motor de justificació Knuth-Plass, l'equilibratge de columnes, el tall òptim de paràgrafs, la numeració de recursos per tipus i la col·locació de flotants.
  • Generació de PDF: construcció de PDF a baix nivell, incrustació de fonts, gestió del color i tractament dels bytes dels recursos per a figures a una tinta.
  • Renderitzat de text: renderitzat sobre canvas, sortida SVG, recoloració de SVG a una tinta (diagramStyle.singleInk) i mètriques de font.
  • Optimització del rendiment: la memòria cau de mesures, l'algorisme de talls de línia Knuth-Plass escrit en Rust i compilat a WebAssembly (rust/), i mantenir el motor prou ràpid per funcionar en temps real cada vegada que es redimensiona la finestra.

#Sandbox i interfície

El Sandbox ja és, per si mateix, una aplicació React considerable: un tauler Recursos amb un editor interactiu de taules i pujada d'imatges i SVG, un tauler Fonts, editors de plantilles de pàgina i de pàgines de còmic, i un tauler Disseny amb grups que arriben a totes les parts del motor. Els controls es construeixen sobre primitives de Base UI (packages/postext-sandbox/src/ui/) i es revisen amb axe-core i amb comprovacions pròpies segons WCAG 2.2 al nivell AAA. Per això, els controls nous les han de reutilitzar, i cada camp ha de tenir el nom que li dona l'etiqueta i la descripció que li dona el text d'ajuda. Totes les cadenes de la interfície segueixen una convenció d'i18n estricta: cada etiqueta passa pel paquet del Sandbox, pel pont d'etiquetes de l'aplicació web i pel catàleg de cadascuna de les deu llengües. Si contribueixes al frontend o a la UX, aquest és el teu terreny.

#Disseny i tipografia

  • Experiència en disseny editorial: si has maquetat revistes, diaris o llibres, saps què fa que una maquetació funcioni (o falli), i aquest coneixement és inestimable. No cal escriure codi.
  • Tradicions tipogràfiques: el projecte ha de respectar les convencions tipogràfiques de llengües i sistemes d'escriptura diferents, no només les de les escriptures llatines.

#Documentació i comunitat

  • Documentació: millorar-la, ampliar-la i mantenir-la. Una documentació clara és el que separa un projecte que la gent pot adoptar d'un que acaba abandonant.
  • Traduccions: la documentació i el lloc web són en deu llengües: anglès, castellà, català, francès, alemany, italià, portuguès del Brasil, xinès simplificat, japonès i àrab. Hi són benvingudes més llengües, i també les revisions de les que ja hi ha.
  • Proves: provar en diferents navegadors i sistemes operatius, i buscar casos límit. Trobar les maquetacions que es trenquen és tan valuós com construir les que funcionen.

#Disseny de format i esquema

El format ja no parteix de zero: els blocs ::resource, les referències en línia :ref i les seccions de configuració tableStyle, captionStyle i diagramStyle ja estan publicats. Ara la feina és fer evolucionar un format establert sense trencar-lo:

  • Gramàtica del document: les notes al marge continuen sent una pregunta oberta, tant de disseny com tècnica.
  • Esquema de configuració: a mesura que creix, el sistema ha de continuar sent prou potent per als professionals i prou senzill per als nouvinguts.
On pots ajudar, d’un cop d’ullQuatre quadrants amb exemples concrets a cadascun: codi i interfície del Sandbox, disseny i tipografia, documentació i comunitat, format i esquema.postextCodi i UI del SandboxKnuth-Plass i flotantsPDF i renderitzatMemòria cau de mesuraUI del Sandbox i i18nDisseny i tipografiaDisseny editorialTradicions tipogràfiquesRevistes i diarisEscriptures no llatinesDocumentació i comunitatMillorar la documentacióTraduccionsProves multinavegadorAcollir els nouvingutsFormat i esquemaDirectives ::resource i :refEsquema de configNotes a peu de pàgina i al margeReferències creuades
No cal tocar codi: una aportació marca la diferència en molts fronts.

#Primers passos

La posada en marxa (clonar el repositori, instal·lar les dependències, executar els tests) està documentada a CONTRIBUTING.md. Per als passos mecànics, comença per aquí.

Un cop ho tinguis tot a punt, hi ha tres accions concretes, de menys a més compromís:

  1. Presenta't a Discussions: explica en què treballes i què t'hi ha portat. Cap pregunta no és massa bàsica, i és la manera més ràpida que la comunitat sàpiga que has arribat.
  2. Agafa un issue etiquetat good first issue: estan triats perquè siguin un punt d'entrada realista, sense necessitat de conèixer cap context històric amagat.
  3. Tradueix la documentació a una llengua nova, o revisa'n una: avui la documentació és en deu llengües. Cada llengua nova arriba a lectors que no poden llegir les altres.

Si penses escriure codi, obre primer un issue per discutir l'enfocament: així s'evita la feina duplicada, i una conversa breu al principi estalvia temps a tothom.

Mantén cada fitxer de codi per sota d'unes 600 línies i cada carpeta per sota d'uns 25 fitxers de codi: un mòdul que creix més es converteix en una carpeta amb el mateix nom, i el fitxer antic queda com a façana que la reexporta. La CI comprova els límits amb node scripts/source-size.mjs --check (vegeu Code Layout a CONTRIBUTING.md).

#Què llegir després

Per orientar-te abans de començar:

  • Arquitectura: com està organitzat el procés de composició i on és cada subsistema.
  • Format del document: la gramàtica de Markdown enriquit que amplien els col·laboradors.
  • Sandbox: el laboratori on és més fàcil veure i provar la majoria dels canvis.

#La comunitat

Postext encara és als inicis, i precisament per això aquest moment és especial. Qui s'hi incorpora ara no només escriu codi: dona forma a les convencions, a les prioritats i a la cultura del projecte.

El projecte valora:

  • Disseny reflexiu abans que velocitat. Encertar les abstraccions importa més que publicar de pressa. La tipografia s'ha refinat durant segles; ens podem prendre el temps de fer-ho bé.
  • Claredat abans que enginy. El codi fàcil de llegir i d'entendre val més que el codi impressionant però opac.
  • Col·laboració abans que territori. Ningú no és amo de cap part del codi. Les idees s'avaluen pel que valen, no per qui les ha proposat.

Tots els col·laboradors tenen reconeixement. Aquest projecte existeix perquè hi ha persones que decideixen dedicar temps a millorar-lo.

#Visió

Postext aspira a convertir-se en el motor de composició estàndard per al contingut editorial al web: l'eina a què recorrin editorials, revistes, diaris i plataformes de llibres quan necessitin tipografia professional.

Si treballes en desenvolupament editorial i fins ara has resolt aquests problemes de maquetació tot sol, et convidem a resoldre'ls d'una vegada, i bé, al costat d'altres.