El Proyecto PEAR

Agenda

• El proyecto PEAR [1]

  • Breve historia
  • Metas y comunidades

• La comunidad de desarrolladores

  • Organización
  • Toma de decisiones
  • Mecanismos de interacción
  • Estándares

¿Qué es PEAR?

• Un proyecto de Código Libre, parte del proyecto PHP [2].
• Un repositorio de código reusable, sólido, bien mantenido, y que ha sido revisado por muchos.
• Una infraestructura para manejo modular de paquetes.
• Una comunidad de programadores con un mecanismo de interacción técnico y social definidos.

Breve historia de PEAR

Metas de PEAR

• Proveer paquetes escritos en PHP, generales e interoperables.
• Requerir alta calidad en el código, y mantener un estilo consistente y claro de programación.
• Asegurar una mejora continua y un mantenimiento sostenido de los paquetes en PEAR.
• Crear un ambiente para el libre intercambio de ideas y experiencias.

Las comunidades de PEAR

PEAR es una comunidad de comunidades.

Desarrolladores

Documentadores

Programadores

Escritores

Educadores

Usuarios finales

Organización

Múltiples grupos internos:

• Un grupo grande de desarrolladores con voz y voto (PEAR Dev).
• Grupo de control de calidad (PEAR QA).
• Grupo de documentación (PEAR DOC).
• Grupo central que administra y toma las decisiones acerca del proyecto (PEAR Group).

Se puede pertenecer a más de un grupo (si uno tiene el tiempo y la energía).

Toma de decisiones

• Los responsables de un paquete deciden como este evoluciona, en función a las necesidades de los usuarios y opiniones de otros desarrolladores.
• El grupo de Control de Calidad [3] asegura de que las versiones que se publica cumplan con las reglas y sean consistentes.
• Temas de importancia general se discuten abiertamente, y el PEAR Group [4] se encarga de hacer oficial la decisión de la comunidad.

Mecanismos de interacción

• Comunicación via diversos medios:

  Listas de correo. IRC. Blogs. Wikis. Reuniones en conferencias, etc.

• Estándares y hábitos/costumbres:

  Código. Documentación. Propuestas de paquetes. Votación. Mantenimiento de paquetes. Control de Calidad, etc.

• Soporte tecnológico:

  CVS. Bug tracker. Sitio web. RSS de nuevas versiones. PEPr. Estadísticas de paquetes, etc.

Estándares y convenciones

Las reglas decididas por la comunidad para regularse a si misma, entre otros:

• Cómo escribir código claro y estructurado.
• Cómo documentar el código.
• Ciclo de vida de un paquete.
• Forma de manejar nombres y versiones de paquetes.
• Procedimientos de votación para las decisiones comunitarias.

Un nuevo paquete

• No debe de duplicar la funcionalidad de un paquete existente. Se pueden hacer excepciones si las razones son extremadamente buenas.
• Debe de tener uso general, y en lo posible, independiente de la plataforma.
• Debe de cumplir con los estándares de PEAR.
• Se deberá someter al proceso de aprobación, aún si el desarrollador tiene múltiples paquetes aprobados previamente.

Aprobación de un paquete

1. Alguien propone un paquete, generalmente, después de discutir la idea en pear-dev (la lista de correos de desarrolladores de PEAR).
2. El paquete puede empezar como "Draft" (borrador) si no tiene código para mostrar, o como "Proposed" (propuesto) si lo tiene.
3. Se hacen comentarios acerca del código, algoritmo usado, etc.
4. Eventualmente se llama a votación, y como resultado se aprueba o rechaza el paquete.

PEPr

• Una herramienta que automatiza algunos de los pasos del proceso de aprobación de paquetes.
• Maneja el flujo de trabajo de un paquete: Borrador -> Propuesto -> En votación -> Finalizado
• Votos en contra (-1), o condicionales, requieren una razón explícita para ser aceptados. Votos neutros (0) o a favor (+1) no necesitan justificación.
• Si al final, un paquete tiene +5 como mínimo, es aprobado.

Estándares de código

• Paquete y sus clases deben tener nombres descriptivos que reflejen su funcionalidad, ej. XML_RSS.
• Los nombres de los componentes siguen convenciones específicas, ej.: getTable(), _pivotMatrix(), DB_ASSOC, etc.
• La estructura física del paquete debe reflejar su estructura lógica: una clase por archivo, etc.
• Reglas para el indentado del código.
• Documentación incluída in-situ.

Estándares de código (1)

• Clases con nombres descriptivos, ej. HTML_Table, XML_RSS, Image_GIS.
• Miembros públicos usan “Camel Caps”, ej. solveEquation(), getStructure().
• Miembros privados se prefijan con subrayado, ej. $_handler, _validate().
• Constantes usan sólo mayúsculas y se nombran de acuerdo al paquete, ej. MATH_STATS_CUMMULATIVE

Estándares de código (2)

• Variables globales deben usar el nombre del paquete con subrayado como inicio, e.j. $GLOBALS[‘_PEAR_default_error_mode’]
• Una clase por archivo, y cada archivo con el nombre de la clase contenida, ej. DB.php
• Jerarquía plana en la estructura de los directorios, correspondiente a donde será instalado, por ejemplo, HTML_QuickForm_Controller, se instalará en: HTML/QuickForm/Controller

Estándares de código (4)

• Líneas de código de 75-85 caracteres.

• Indentado de 4 espacios, no tabulaciones.

• Las funciones usan el estilo “one true brace”:

  function getEntry($row, $col)

  {

  // cuerpo del método

  }

Estándares de código (5)

• Estructuras de control deben de siempre usar llaves:

  if ($obj->isValid()) {

  // procesarlo

  } else {

  // manejar el problema

  }

Estándares de código (6)

• Sólo se permite usar <?php ?> para marcar el bloque de código de PHP.
• Inclusión incondicional de código debe de usar require_once, mientras que la inclusión condicional usará include_once.
• Comentarios deben usar el estilo de C (/* */) o de C++ (//).

Documentación (1)

• Las clases, miembros públicos, constantes, etc. deberán tener documentación embebida usando usando las convenciones y marcados de PhpDocumentor.
• La documentación del API será generada en forma automática para cada versión
• Paquetes considerados estables (stable) deberán de proveer documentación para el usuario final, en adición a la generada para su API.

Documentación (2)

• La documentación que se incluya en el manual se escribirá usando Docbook XML (con modificaciones locales).
• Adicionalmente, se puede incluir un tutorial corto como parte de la documentación en el manual.
• Grupos de traductores deberán mantener el manual al día con respecto a la versión en inglés.

Trabajando en comunidad

• Que hace el PEAR QA (grupo de control de calidad)

• Que hace el PEAR Group

  Caso específico: Problema de seguridad con XML_RPC (2005)

• Cómo se organiza y trabaja el PEAR Doc (grupo de documentación)

• Otros roles/trabajos: Web master, administrador de los servidores, etc.

Contribuciones de fuera

Usuarios finales y otra comunidades nos han dado importantes contribuciones:

• Reportes de problemas y defectos.
• Diseños gráficos (logos, banners, íconos, etc.)
• Código útil que hemos reusado.
• Material didáctico (presentaciones, talleres, libros, etc.)
• Ideas para mejorar algoritmos, código, etc.
• Soporte directo para algunas actividades.

Palabras finales

• Trabajar en comunidad no es sencillo, pero vale la pena.
• Debemos ir con una mente abierta y dispuesta a aprender.
• Encontraremos culturas, convenciones y formas de trabajar diferentes, y eso es bueno.
• El involucramiento en una comunidad es un proceso continuo y que evoluciona. No hay que tener miedo de comenzar con poco.
• Al final del día, todo esto es una oportunidad de mejorarnos, hacer amigos y divertirnos.

Referencias

• PEAR: http://pear.php.net/

  • Manual: http://pear.php.net/manual/
  • Paquetes: http://pear.php.net/packages.php
  • PEPr: http://pear.php.net/pepr/
  • Bugs: http://pear.php.net/bugs/
  • Libros: http://pear.php.net/support/books.php

• Charlas acerca de PHP (y PEAR): http://talks.php.net

¡Gracias!

¡Participen en las comunidades de Código Libre!

http://pear.php.net/

[Descargar esta presentación]