Gestión de los documentos de la asociación (BORRADOR)

Los documentación de la asociación se hospeda en un repositorio Mercurial. Es accesible de forma pública, en lectura, tanto por web como con la descarga de un “clon” Mercurial.

Modificaciones en el repositorio

Para poder modificar los documentos, es necesario o bien tener acceso PUSH al repositorio o bien clonarlo en otro lugar y luego ofrecer o bien un “diff” o la opción de “PULL” desde el repositorio “clon”.

  • Procuraremos hacer la edición en la última versión del repositorio.

    Advertencia

    Es conveniente hacer un:

    $ hg incoming -p

    para ver qué cambios nos van a llegar y para verificar que no se van a aceptar modificaciones maliciosas en ficheros peligrosos, como conf.py o Makefile, entre otros.

  • Todos los identificadores de usuario visibles en la historia del repositorio deben aparecer como “nombre <email>”.

  • Salvo causas muy justificadas, el formato oficial de los documentos de la asociación es reStructuredText. Cuando el formato final de salida no sea un formato nativo de Sphinx, se debe incluir el procedimiento exacto de generación del documento, incluyendo los recursos asociados necesarios: reglas de estilo, Makefile, etc.

  • La edición de los documentos debe realizarse usando el juego de caracteres UTF-8.

  • El idioma oficial de la asociación Python España es el español/castellano.

    Puntualmente pueden aceptarse documentos en inglés u otros idiomas, de forma justificada.

  • Tras un punto y seguido, se pone un único espacio.

  • Bajo ningún concepto deben modificarse los ficheros que se ejecutan para regenerar la documentación, como conf.py o Makefile, entre otros.

  • Por favor, cuidad la ortografía y la gramática, y pasad un corrector ortográfico a los textos nuevos.

  • Se debe intentar mantener el tono y estilo de los documentos ya existentes.

  • En lo posible, los párrafos nuevos tendrán una anchura de 66 caracteres.

  • En general, no debe reformatearse un párrafo ya existente que se haya modificado para ajustarlo a 66 columnas. De esta forma se facilita el seguimiento visual de cambios mediante:

    $ hg diff -c

  • Se puede ver cómo quedan los cambios en la web teniendo Sphinx instalado y haciendo:

    $ make html

    Tendremos los documentos html en local, en el directorio build/html/.

  • En el caso de que se disponga de permiso PUSH, es muy conveniente asegurarse de lo que se va a publicar, mediante el comando:

    $ hg outgoing -p

    Recordemos que una vez que se publica un cambio, permanecerá en la historia del repositorio para siempre.

  • Cambios lógicamente distintos, deben realizarse en “commits” diferentes.

  • El texto del “commit” debe ser explicativo, sin ser redundante con el parche en sí. Es más interesante explicar el por qué, que explicar el cómo. Esto último se puede ver haciendo un:

    $ hg diff -c

  • Salvo causa muy justificada, y previa autorización, no deben crearse “named branches” ni “heads” adicionales en el servidor. La opción recomendada para hacer frente a un conflicto es un “rebase” (preferible a un “merge”, aunque este último puede estar justificado en algunos casos), siempre que no se hayan compartido los cambios con nadie más.

Nota

Hay que documentar qué ocurre con los retornos de carro/saltos de línea de las diferentes plataformas.

Uso de un repositorio externo

Cuando es necesario compartir con otros los cambios en progreso, resulta conveniente utilizar un repositorio externo. El procedimiento concreto a emplear es personal, pero se recomiendan aplicar las prácticas habituales de Mercurial.

Un ejemplo de Work Flow puede ser:

  1. Creamos un clon del repositorio de la asociación que queremos editar de forma conjunta con otras personas, en el servidor de nuestra elección (por ejemplo, BitBucket).

  2. Descargamos el clon en nuestro ordenador, para tener un nuevo clon.

  3. En el clon de nuestro ordenador, editamos el fichero .hg/hgrc. En la sección [paths] añadimos algo del tipo oficial = URL, donde URL es la URL del repositorio original oficial. Por ejemplo:

    oficial = https://hg.es.python.org/asociacion

    En este momento, los hg pull y hg push van al repositorio externo que hemos creado para compartir con otra gente, pero un:

    $ hg pull oficial -u

    va a descargar los cambios del repositorio oficial.

    Se recomienda leer la documentación con detalle, haciendo:

    $ hg help paths

    Podemos ver los nombres definidos actualmente, para el clon en curso, haciendo:

    $ hg paths

  4. Ahora trabajaremos de forma normal, publicando los cambios en el repositorio externo, a disposición del resto de colaboradores. Para mantener una separación entre nuestros cambios y las actualizaciones del repositorio canónico, puede ser conveniente crear un “named branch”:

    $ hg branch MI_RAMA

    A partir de ahora, los commit que hagamos se pondrán en esa rama separada.

  5. Para recibir las actualizaciones del repositorio oficial, podemos hacer, por ejemplo, algo del tipo:

    $ hg pull oficial

    Esos cambios se pueden mantener como un “head” adicional, un “rebase” o hacer un “merge”, según el workflow y la experiencia de cada cual.

    En el caso de estar empleando un “named branch”, la opción recomendada es:

    $ hg up -r MI_RAMA
$ hg merge -r default

  6. Una vez que se cierran los cambios en el repositorio externo y se desea consolidarlos con el repositorio oficial, hay varias posibilidades, en función de la naturaleza de los cambios, la habilidad de cada uno y el interés que exista en preservar la historia. Y de si el colaborador dispone de permisos de “push” al repositorio oficial o no.

    Advertencia

    A la hora de hacer cambios en el repositorio oficial, es necesario seguir las directrices expuestas en la sección anterior. Por ejemplo, no tener cabezas ni ramas múltiples.

    • Si el usuario tiene permiso de “push” al repositorio oficial, interesa mantener la historia y esta está limpia y clara, sin reescrituras inconsistentes del histórico, se puede hacer un simple:

      $ hg outgoing -p
$ hg push oficial

    • Si se han añadido documentos nuevos, pero no se ha tocado nada ya existente, una opción simple es copiar los ficheros nuevos en un clon del repositorio oficial, y subirlos sin más.

    • Si se usa BitBucket o similar, hay que explicar el uso de los “pull request”.

    • Otra posibilidad es utilizar un “named branch” para los cambios en progreso, y aplicar el diff entre dicha rama y la rama default que es la utilizada en el repositorio oficial:

      $ hg diff -g default MI_RAMA > cambio.patch
$ cd clon_limpio_repositorio_oficial
$ patch -p1 < MI_CLON/cambio.patch

    • A las malas, se puede pedir ayuda a Jesús Cea :-).

    Advertencia

    Siempre que se vayan a hacer cambios en el repositorio oficial, es MUY recomendable revisar primero qué se va a enviar exactamente, con:

    $ hg outgoing -p

    Recordemos que una vez que se publica algo en el repositorio oficial, permanecerá en la historia para siempre.

Publicación de los cambios en la web de la asociación

Los cambios en el repositorio de documentación se publican haciendo lo siguiente: [1]

  1. Actualizar el repositorio local.

Advertencia

Es conveniente hacer un:

$ hg incoming -p

para ver qué cambios nos van a llegar y para verificar que no se van a aceptar modificaciones maliciosas en ficheros peligrosos, como conf.py o Makefile, entre otros.

  1. Se revisa la idoneidad de los cambios, ortografía, etc.

  2. Hacemos:

    $ make html

    para regenerar los ficheros HTML, Javascript, etc.

  3. Se suben los ficheros al servidor con:

    $ ./z-rsync-produccion

  4. Visitamos el sitio web de la asociación para asegurarnos de que la documentación se ha subido correctamente.

Notas

[1]En la actualidad este procedimiento lo realiza Jesús Cea.