wiki:DocumentacionDesarrollo/BuenUso

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, ...".
Last modified 2 months ago Last modified on Jul 14, 2017, 1:07:08 PM