Welcome to Genweb’s documentation!

Note

At the time of this writing, this documentation exist only in catalan.

Introducció

Aquesta és la documentació oficial de desenvolupament de la col·lecció de paquets de software que composen Genweb.

Genweb és un generador de webs institucionals inicialment orientat a donar servei a les unitats, serveis i facultats de la Universitat Politècnica de Catalunya (Barcelona Tech). Està basat en el gestor de continguts de software lliure Plone. Fa servir tecnologies HTML5, i està basat en el llenguatge de programació Python.

El servei Genweb UPC és una iniciativa del Servei de Comunicació i Promoció de la UPC i UPCnet i abraça no només el desenvolupament del software base (Genweb), sino també el hosting de totes les instancies que actualment es troben en producció. Actualment qualsevol unitat, departament, servei i facultat de la UPC pot gaudir del servei via petició al Servei de Comunicació i Promoció de la UPC. Més de 400 entitats ja gaudeixen del servei. Amb més de 5 anys d’història, el servei ha viscut moltes actualitzacions a lo llarg d’aquests anys i està activament mantingut per UPCnet.

Motivació

Aquesta documentació ve motivada per la necessitat de tindre un punt únic d’entrada on compartir la informació relacionada amb com està desenvolupat Genweb i les bones pràctiques relacionades amb el seu desenvolupament.

Continguts

Manual de bones pràctiques

Aquest document exposa algunes de les bones pràctiques que es recomanen quan desenvolopeu el projecte Genweb.

PEP8

És important mantindre un codi d’estil unificat basat en l’estàndar Python PEP8. Aquest codi el podeu trobar a:

http://www.python.org/dev/peps/pep-0008/

Hi han eines validadores de codi (linters) pels editors més comuns que validen PEP8, per exemple SublimeText2 te un plugin linter per PEP8.

Vistes

Genweb disposa del framework de desenvolupament Grok, que permet declarar vistes i viewlets de manera imperativa via Python sense necessitat de declarar-los via ZCML. Així es manté unificat el codi i la declaració de la vista.

En la mida de lo possible, utilitzarem Grok per totes les vistes i viewlets. En cas de haver de fer overrides, es farà via ZCML.

Editor / IDE

Es recomana utilitzar l’entorn de desenvolupament (IDE) Sublime Text 2. En l’últim any s’ha convertit en referència de la comunitat i disposa de molts plugins que faciliten el treball diari del desenvolupador.

Note

Podeu trobar més informació de com instal·lar Sublime Text 2 i els plugins més interessants a: http://upcnet-gc-docs.readthedocs.org/en/latest/

git i Github

El VCS que es fa servir a Genweb és git. Es troba hostatjat en el servei de social coding Github .

Els paquets de Genweb pengen de la organització UPCnet de Github i són públics. Genweb és codi lliure sota la llicència GPL v2. Aquest és la URL:

http://github.com/UPCnet

La manera de treballar amb git és amb branques i tags per releases finals. Aquestes branques segueixen el estàndar:

master
Per releases finals. Codi “ready for production”
develop
Versions beta i encara no publicades i probablement, codi no llest per producció. Branca que te els canvis que es publicaran en la següent release.
<altres branques no permanents>
Branques de alphas i de codi que encara no está acabat. Poden ser locals a cada desenvolupador o compartides en servidor.

Només els usuaris (de Github) autoritzats a la organització poden fer canvis en els repositoris. Els usuaris que vulguin contribuir amb codi a Genweb ho han de fer via “pull requests” de Github. El codi es revisarà i es farà el “merge” si és convenient.

Note

Per més informació sobre git i github, podeu consultar: https://help.github.com/

Testing

El dessitjable és que Genweb tingui el màxim de codi cobert per testos automatitzats. Genweb disposa de una col·lecció de testos d’integració, funcionals i d’acceptació globals a la totalitat del codi que composa Genweb. Per lo tant, aquest codi comprova per exemple si es creen bé tipus de contingut comuns corresponents a paquets diferents i si funcionen bé en el contexte global de Genweb.

A més, cada paquet pot tindre els seus propis testos.

La forma de llençar els testos:

<directori_buildout>/bin/tests -s genweb.core

Per altres paquets:

<directori_buildout>/bin/tests -s genweb.controlpanel

Travis CI

Travis CI és un entorn en cloud de integració contínua (CI). Aquest entorn està enllaçat amb Github de manera que cada cop que un desenvolupador puja (commit) o fa una petició de pujada (pull request) s’executan els testos del paquet en concret, tenint d’aquesta manera control total sobre si el codi que s’ha pujat és correcte i no trenca el paquet.

Cada paquet te enllaçat un “hook” de Github per a que Travis sàpiga que ha de fer la seva feina quan es puja codi.

EGGS (paquets) que composen Genweb

genweb.core

És el paquet bàsic i principal del projecte. Dins del punt de vista de la totalitat i d’arquitectura del software del mateix, constitueix el pilar a on es sustenten tots els altres paquets i punt de partida dels mateixos. Aquest paquet és estratègic que només contingui funcionalitats i parametrització d’un hipotètic site Genweb. L’objectiu principal és que al instal·lar-lo el site resultant no contingui cap caracterítica diferenciadora en quant a “look and feel”. Si per alguna raó ha de renderitzar en presentació alguna element o dependre en codi d’algun element, en cap manera aquest element ha de dependre d’altres paquets per al seu funcionament, al contrari, les dependències de paquets que declara i que instal·la són merament per afegir funcionalitats interessants al conjunt de funcionalitats de Genweb (p.e. Products.PloneFormGen).

genweb.controlpanel

És el paquet que conté el nou panell de control de Genweb (a partir de 4.2). Es basa en plone.registry. Conté testos associats.

genweb.theme

És el nou paquet que conté el tema (look and feel) i interfície de Genweb. És important que aquest paquet només contingui elements de personalització gràfica de Genweb UPC. No ha de contindre cap element funcional ni que aporti funcionalitat al conjunt.

genweb.stack

És el paquet que conté dependències amb altres paquets que afegeixen funcionalitats interessants a Genweb.

genweb.portlets

És el paquet que conté tots els portlets personalitzats per Genweb, inclosos els overrides dels originals.

Historial de canvis

Changelog

4.3 (2013-06-10)

  • First 4.3 (Plone 4.3 based) branch stable version

4.3b2 (unreleased)

  • Un-grok the genweb.utils convenience view to BrowserView configured by ZCML, added the allowed_interfaces needed to access unrestricted to all the utilities methods.

4.3b1 (unreleased)

  • New versioning number for the 2013 version of Genweb UPC: “rovelló de pi”.
  • New implementation from scratch, base of all the 2013 developments.
  • Traspassada tota la funcionalitat del paquet upc.genwebupc
  • Traspassats configuració genérica del profile del paquet upc.genwebupctheme

4.1.4 (2012-03-01)

  • Permissos del root

4.1.3 (2011-12-19)

  • Stripped tags al setuphandlers

4.1.2 (2011-12-12)

  • Traduccions

4.1.1 (2011-11-30)

  • Actualitzar nasty tags al setuphandlers

4.1 (2011-11-25)

  • Actualització a Plone 4.

4.0b2 (dev)

Nova versió del paquet, amb els viewlets updatats. - Deprecat el viewlet de toolbar, updatant el de per defecte de Plone 4. - Afegida l’acció d’usuari ‘carpeta arrel’. - Updatat el viewlet d’idiomes, utilitzant la estructura del original. - Inclusió de la vista de utilitats genweb.utils per *. - Desconfiguració dels viewlets per a configuració posterior. - Update dels arxius .po i canvi al domini ‘genweb’

4.0b1 (2010-11-10)

  • Ajustat les dependencies
  • Eliminat el CKEditor
  • Versió aplicada en Web UPCnet.

3.3dev (unreleased)

  • Initial release