Buen uso del gestor de proyectos

Introducción

El grupo de desarrollo de OpenGnSys ha optado por utilizar el gestor de proyectos Trac y el repositorio de código Subversion. En esta página se presenta una breve lista de recomendaciones a la hora de utilizar estas herramientas.

Wiki

Consideraciones generales

• Seguir las normas de Trac para formatear la información (ver WikiFormatting).
• Los nombres de las páginas del wiki deben seguir la nomenclatura recomendada por Trac (ver WikiPageNames).
• El idioma por defecto de las páginas es el español.
• Una página traducida debe crearse con el nombre Página/Idioma, indicando el nombre abreviado para el idioma, por ejemplo en para inglés (ver WikiNewPage).

Estructura recomendada

• Para una página con traducción o en el caso de que vaya a ser traducida, ésta debe empezar con la macro:

  [[TranslatedPages]]
  

• Todas las páginas del wiki deben incluir un índice.
  • Para información en español añadir la macro:

    [[PageOutline(2-5,Índice)]]
    

  • Para páginas en inglés, añadir:

    [[PageOutline(2-5)]]
    

• Puede indicarse una información destacada en un recuadro de noticias, incluyendo la macro:

  {{{
  #!NewsFlash
  Información
  }}}
  

• Sólo debe incluirse una cabecera de primer nivel indicando el título de la página (no será incluido en el índice):

  = Título =
  

• Pueden incluirse tantos subtítulos de distinto nivel como se considere oportuno, manteniendo una estructura correcta para el índice de la página.
• Las referencias a otras páginas del wiki, incidencias, listas de cambios, direcciones externas, etc., deben seguir las recomendaciones establecidas por Trac (ver TracLinks).
• Puede incluirse cualquier macro instalada en el sistema (ver WikiMacros).
• Asimismo, el texto puede formatearse para ofrecer un aspecto personalizado, tablas complejas o resaltar código (ver WikiProcessors).
• Identificar claramente bloques de código.
  • Si está incluido en el párrafo de texto, añadir: {{{Código}}}
  • Para bloques grandes de código, añadir:

    {{{
    Código
    }}}
    

  • Para resaltar la sintaxis de código de lenguajes de programación como C (c), C++ (cpp), Shell (sh), PHP (php) etc (ver WikiProcessors#CodeHighlightingSupport), añadir:

    {{{
    #!lenguaje
    Código
    }}}
    

• Incluir las etiquetas adecuadas para el buscador del portal, según las recomendaciones establecidas.
• Incluir siempre una breve descripción de los cambios aplicados en la página.

Incidencias

Crear nueva incidencia

• El idioma preferido para redactar nuevas incidencias es el español.
• Rellenar adecuadamente todos los campos del formulario de incidencias.
• Indicar en el resumen si la incidencia afecta a una rama de desarrollo que no es la principal.
• Incluir una descripción completa de la incidencia con un formato similar al del wiki (ver WikiFormatting).
• Establecer unos valores adecuados para la prioridad de resolución, la gravedad de la incidencia, el componente afectado, etc.
• Incluir las etiquetas (palabras clave) adecuadas, según las recomendaciones establecidas.

Modificar incidencias

• Responder a una incidencia en el mismo idioma que la redacción original.
• Incluir una descripción completa de los cambios realizados en una incidencia.
• Aceptar las incidencias que serán resueltas por el propietaria.
• Modificar adecuadamente el estado de resolución de la incidencia.
• Cambiar el resto de campos del formulario sólo en los casos de reestructuración de componentes o redefinición de la incidencia.

Etiquetas

• Una etiqueta debe ser una única palabra escrita siempre en minúsculas (por ejemplo opengnsys)
• Usar el carácter guión para agrupar varias palabras en una única etiqueta (por ejemplo sistema-de-archivos).
• Añadir tantas etiquetas de búsqueda como sean necesarias para calificar adecuadamente el contenido de la página.
• Verificar que las etiquetas existen en la lista antes de incluir alguna nueva (ver etiquetas).

Revisiones de código

• Siempre que sea posible, realizar revisiones de código coherentes y que afecten a un conjunto limitado de características, evitando las revisiones que incluyan un gran número de ficheros.
• Las revisiones que afectan a un conjunto amplio de incidencias sólo deben aplicarse en el caso de mezclar ramas de código.
• Evitar en lo posible el envío de ficheros binarios (que puedan ser compilados en la instalación), temporales, copias, etc.
• Incluir siempre un resumen descriptivo de los cambios en el commit de la revisión.
• El idioma preferido para el resumen de cambios será el español.
• En el resumen de cambios puede hacerse referencia a las incidencias afectadas, incluyendo dentro del mensaje "Refs #NºIncidencia, ...".
• Puede aplicarse automáticamente el cierre de las incidencias corregidas, añadiendo en el resumen la cadena "Close #NºIncidencia, ...".