Premio PFC con Sw Libre

Logo do último post onde introduciamos os conceptos básicos dun sistema de control de versións, neste imos simular unha sesión de traballo habitual contra un proxecto de software libre.

Para iso escollemos o noso obxectivo. Neste caso imos usar un código que recupera perfís de usuarios e os artistas máis escoitados da plataforma last fm. O programa está feito na linguaxe perl e usa a API de last fm para facelo. A nosa tarefa será documentar o que fai cada unha das funcións do código.

O que necesitamos nun primeiro momento é ter instalado no noso ordenador un cliente svn para conectarnos ó servidor e descargar o código. En Ubuntu o paquete a instalar chámase subversion.

OBTENCIÓN DO CÓDIGO FONTE E REALIZACIÓN DE CAMBIOS

Unha vez o temos imos crear un directorio de traballo temporal para realizar esta sesión. Nunha consola (o símbolo $ indica que son comandos de shell o que vai a continuación) facemos o seguinte:

$ mkdir /tmp/lastfm_test

$ cd /tmp/lastfm_test

$ svn checkout uri_svn .

uri_svn = https://svn.forge.morfeo-project.org/svn/freeswmaster/trunk/amaneiro/perl-workshop/

Neste momento temos o código á nosa disposición e podemos empezar a traballar con él.

Si agora observamos as diferencias da nosa copia local de traballo (coñecida como working copy) con respecto ó repositorio (comandos svn diff, svn status) veremos que a saída de ambos comandos é vacía. Lóxicamente, debe ser así, porque aínda non fixemos ningunha modificación con respecto ó código que nos descargamos. É un bo momento para ver tamén a historia do proxecto (usando o comando svn log) e xogar coas múltiples opcións que posúe.

Para seguir coa sesión, abrimos o noso editor favorito e modificamos o ficheiro ex11.pl documentando cada unha das funcións.

Unha vez rematemos, podemos observar os cambios: cómo variou o estado da nosa copia local de traballo con respecto ó repositorio. Comprobamos os ficheiros modificados (comando svn status) e logo as modificacións introducidas en cada un deles (comando svn diff).

SUBINDO OS CAMBIOS REALIZADOS

Agora que sabemos que os cambios que se realizarán son os correctos, debemos asegurarnos de ter a última versión do código do repositorio, pois é posible que alguén máis estivese traballando en paralelo e o código que teñamos na nosa copia local de traballo esté desactualizado con respecto ó repositorio. Actualizamos pois a nosa copia de traballo (comando svn update).

Unha vez resoltos os posibles conflitos existentes, estamos listos para enviar os cambios ó repositorio. Pode darse calquera das 2 situacións seguintes:

1. Temos unha conta propia no repositorio do proxecto: podemos enviar os cambios directamente.
2. Non temos conta no repositorio do proxecto: debemos enviar os cambios a alguén que teña conta.

No primeiro caso bastaría con facer:

$ svn commit

Automáticamente abriríase o editor de texto predeterminado do sistema e no arquivo que nos abre escribimos unha breve descripción dos cambios realizados (“documentación das funcións” no noso caso). Gardamos o arquivo e cerramos o editor. Os cambios son enviados ó repositorio.

Si estamos na segunda opción (non temos conta) debemos enviar un parche ás listas do proxecto para que o revise e o inclúa no repositorio si o considera oportuno.

CÓMO ENVIAR UN PARCHE

Como xa dixemos, é posible que non teñamos acceso ó repositorio para subir os cambios. Neste caso, a estratexia a seguir consiste en realizar un informe das diferencias entre a nosa copia local de traballo e o repositorio. Será iso o que lle enviaremos ás listas do proxecto para que vexan os cambios e os apliquen sobre o repositorio si o creen conveniente.

Para facer isto existen as ferramentass diff (que compara arquivos liña por liña) e patch (que aplica un parche determinado sobre un arquivo). Así, un parche pode entenderse como un informe de cambios respecto a un (ou varios) arquivo(s). Podedes observar as funcionalidades de cada unha delas na propia páxina do manual. Para o caso que nos ocupa, o propio cliente de subversion trae integrada a posibilidade de facer un diff da copia de traballo con respecto ó repositorio.

O único que temos que facer para ter un arquivo cos cambios respecto ó repositorio é:

$ svn diff > parche.diff

Deste modo, no ficheiro parche.diff temos os cambios ficheiro por ficheiro. Éste arquivo será o que se envía ás listas do proxecto para que comproben que o parche é correcto, se discuta e se aplique en último caso.

Cada proxecto ten as súas normas sociais á hora de enviar parches, mais en xeral, boas prácticas á hora de realizar e enviar un parche son:

• Realizar o parche sobre a última revisión do proxecto.
• Enviar o parche á lista de correo do proxecto, non directamente ó programador.

De cara observar a complexidade do envío e posterior revisión do parche ata que éste sexa aceptado ou rexeitado, son boas referencias as seguintes guías:

• How to participate in the linux community
• Contribute / Send patches to KDE

RESUMO

Ó longo deste post, seguimos o seguinte fluxo de traballo:

1. svn checkout uri_svn # descargamos o código do proxecto
2. (traballamos na tarefa que nos ocupaba: documentación neste caso)
3. svn update # actualizamos os nosos cambios con outros que puideron facer os programadores
1. (si non existen conflictos pasamos ó punto 4)
2. (revisar e resolver os conflictos si existen, logo volver ó punto 3)
4. svn status; svn diff # comprobamos que os cambios rexistrados sexan os correctos
5. svn commit # subimos os cambios ó repositorio

uri_svn = https://svn.forge.morfeo-project.org/svn/freeswmaster/trunk/amaneiro/perl-workshop/

Tamén vimos cómo construir e enviar parches no caso de non ter acceso ó repositorio directamente. A partir deste momento, estamos listos para colaborar en calquera proxecto!