Cómo modificar el código de otros

GNOME es un proyecto de equipo, así las contribuciones de código a programas de otras personas siempre son apreciadas. Sigue los siguientes lineamientos cuando modifiques el código de otra persona.

Etiqueta general

Siga el mismo estilo de indentación usado en el código original. El código original perdurará durante más tiempo que el que le pueda dedicar, mantener las contribuciones consistentes respecto a la indentación es más importante que forzar su estilo de indentación en el código.

Aunque sus parches pueden implementar una funcionalidad muy llamativa, es muy molesto para el autor tener que reindentar el código antes de aplicar un parche al código principal. Así, si el código original luce como:

int
sum_plus_square_of_indices (int *values, int nvalues)
{
	int i, total;

	total = 0;

	for (i = 0; i < nvalues; i++)
		total += values[i] + i * i;

	return total;
}

entonces no agregues una función que luce como:

int sum_plus_cube_of_indices(int *values, int nvalues) {
  int i,total;

  total=0;

  for (i=0;i<nvalues;i++)
    total+=values[i]+i*i*i;

  return total;
}

En el segundo ejemplo, la indentanción y ubicación de las llaves no coincide con el código original, no hay espacios alrededor de los operadores y el código no se parecerá al original. Sigue el estilo de programación del autor original del programa y los parches que envías tendrán una mejor oportunidad de ser aceptados.

No repares errores con artilugios o hacks rápidos; repáralo correctamente. Tampoco añadas características como hacks o con código que no sea extensible; es mejor rehacer el código original para que sea extensible y luego agrega la nueva característica, utilizando el código como estructura.

La limpieza de código siempre es bienvenida; si encuentras trozos de código feos y sucios en GNOME, será muy apreciado si envías parches que hagan el código más agradable y fácil de mantener.

Como siempre, asegúrate de que el código que contribuye compila sin ningún tipo de aviso, que tenga los prototipos correctos y que sigan las directrices de este documento.

Cómo documentar los cambios

GNOME utiliza los archivos ChangeLog estándar de GNU para documentar los cambios al código. Cada cambio que efectúes a un programa debe ser acompañado por una registro en el ChangeLog. Esto permite a las personas leer la historia de cambios del programa de una manera sencilla.

Si usas Emacs, puede agregar las líneas al ChangeLog presionando «C-x 4 a».

Nota

Si conoces la forma de realizarlos para otros editores populares, agradeceremos que nos lo hagas saber para expandir este documento.

Cada registro en el ChangeLog tiene un forma general:

1999-04-19  J. Random Hacker  <jrandom@foo.org>

	* foo.c (some_function): Changed the way MetaThingies are
	frobnicated.  We now use a hash table instead of a linked list to
	look MetaThingies up.
	(some_other_function): Support the MetaThingies hash table by
	feeding it when necessary

	* bar.c (another_function): Fixed bug where it would print "Take
	me to your leader" instead of "Hello, World".

1999-04-18  Johnny Grep  <grep@foobar.com>

	* baz.c (ugly_function): Beautified by using a helper function.

Si agregas una nueva función a una biblioteca, escribe la referencia necesaria y la documentación de programación. Puedes escribir una referencia a la documentacion en línea usando el formato de comentarios descrito en gnome-libs/devel-docs/api-comment-style.txt. Si usas Emacs, gnome-libs/tools/gnome-doc/gnome-doc.el provee un acelerador que puede ser empleado para añadir una plantilla de documentación al programa.

Cómo actualizar en CVS

Si tienes acceso de escritura en el repositorio CVS de GNOME, debes seguir algunas políticas adicionales. Ya que estás trabajando en la copia maestra de los fuentes, debes tener especial cuidado.

Si estás reparando algo en un programa que está en el CVS o si estás añadiendo una funcionalidad allí, y si no has estado trabajando en dicho programa por un período largo de tiempo, pregunta al autor original antes de aplicar sus parches. Generalmente está bien formular estas preguntas en la lista de correo gnome-devel-list.

Una vez que el autor del programa te indique como un ‘contribuyente frecuente’, puedes comenzar aplicar los parches sin previo consentimiento. Si quieres aplicar una reorganización mayor del código, debieras preguntar primero.

Algunos módulos en el CVS tienen rama estable y de desarrollo. Normalmente el desarrollo debiera ir en la rama HEAD en el CVS, y la rama estable debiera mantenerse separadamente. Generalmente no se añaden nuevas características a las rama estable; sólo se reparan errores. Repara el error a la rama estable y pregunta al autor principal sobre la política para mezclar parches en la rama de desarrollo; algunos autores prefieren hacerlo por lotes, mientras hay otros que prefieren mezclarlos inmediatamente.

Si trabajas en una característica experimental que podría estropear mucho código, crea una rama en el CVS y realiza los cambios allí. No los mezcles en la rama principal de desarrollo hasta que te encuentres razonablemente seguro que funcionará correctamente y que se integrará bien dentro del resto del código. El uso de una rama para trabajo en características experimentales te permitirá evitar interrumpir el trabajo de otros desarrolladores. Pregunte al autor principal antes de mezclar tu rama y traer sus cambios a la parte principal del árbol.

Como siempre, agrega un registro en el ChangeLog cuando realices un cambio. Algunos autores tienen la política de rechazar, correctamente, los cambios que no tienen tal registro.

Algunas veces existen diferentes políticas para los módulos, verifica si el módulo contiene un archivo README.CVS. Si es así, lee ese archivo antes de realizar cambios.

Ramas y marcas

Tenemos una convención para nombrar las ramas y marcas o puntos de una rama en el repositorio de CVS de GNOME. Las marcas deben ser definidas después que se libera cada nueva version y deben ser de la forma «MODULE_MAJOR_MINOR_MICRO», por ejemplo, «GNOME_LIBS_1_0_53». Los puntos de una rama deben ser de la forma «MODULE_BRANCH_ANCHOR», como en «GNOME_LIBS_1_0_ANCHOR». Finalmente, una rama raíz en este punto debiera ser de la forma «module-branch», por ejemplo, «gnome-libs-1-0». Usa esta convención cuando crees marcas, puntos de una rama y ramas.

Políticas adicionales del CVS

CVS no proporciona un manera preconstruida para renombrar archivos o moverlos a otros directorios. Debiera planificar cuidadosamente el árbol del repositorio de tal forma que evite mover o renombrar archivos.

En el caso que debas mover o renombrar un archivo en el CVS, NO EJECUTES «cvs remove» y luego «cvs add». Si lo haces, los archivos «nuevos» perderán la capacidad de seguir su historial de cambios, ya que desde el punto de vista de CVS serán archivos completamente nuevos en su revisión inicial. Un objetivo del repositorio CVS de GNOME es poder seguir la historia de los fuentes de manera precisa desde el inicio.

Por favor, pregunte al mantenedor del CVS, esto es, una persona conocida con acceso shell a la máquina con CVS, para realizar la cirugía necesaria para mover los archivos por ti. Esto requiere conocimiento de la forma en que funciona CVS y debe ser hecho muy cuidadosamente. La recuperación de un error de «cvs add/remove» es una tarea muy desagradable; Si mueves archivo en esta forma equivocada, un mantenedor del CVS, quien tendrá que ir a reparar y realizar el trabajo sucio, reclamará las penas del infierno. Así es que mejor pregunta por una persona que pueda mover los archivos por ti.