Contribuir a LinuxCNC

El repositorio oficial git de LinuxCNC está en https://github.com/linuxcnc/linuxcnc/

Cualquiera puede obtener una copia de solo lectura del árbol fuente de LinuxCNC a través de git:

Si eres un desarrollador con acceso push, entonces sigue las instrucciones de github para configurar un repositorio donde puedas hacer push.

Ten en cuenta que el comando clone coloca el repositorio local de LinuxCNC en un directorio llamado linuxcnc-dev, en lugar del predeterminado linuxcnc. Esto se debe a que el software LinuxCNC por defecto espera configuraciones y programas en código G en un directorio llamado $HOME/linuxcnc`, y tener el repositorio git ahí mismo causa confusiones.

Issues y pull requests (abreviado PRs) son bienvenidos en GitHub: . https:///github.com/LinuxCNC/linuxcnc/issues . https://github.com/LinuxCNC/linuxcnc/pulls

Utilizamos los flujos de trabajo git "merging upwards" y "topic branches" descritos aquí:

https://www.kernel.org/pub/software/scm/git/docs/gitworkflows.html

Tenemos una rama de desarrollo llamada master, y una o más ramas estables con nombres como 2.6 o 2.7 que indican el número de versión de los lanzamientos que hacemos.

Las correcciones de errores van en la rama estable aplicable más antigua, y esa rama se fusiona con la siguiente rama estable más nueva, y así sucesivamente hasta master. El committer o confirmador de la corrección de error, puede hacer las fusiones por sí mismo, o dejarlas a otra persona.

Las nuevas características generalmente van en la rama master, pero algunos tipos de características (específicamente controladores de dispositivo y documentación bien aislados) pueden (a discreción de los gerentes de la rama estable) entrar en una rama estable y fusionarse como lo hacen las correcciones de errores.

Hay muchos excelentes tutoriales gratuitos de git en Internet.

El primer lugar para buscar es probablemente la página de manual "gittutorial". Se puede acceder a esta página de manual ejecutando "man gittutorial" en una terminal (si tiene instaladas las páginas de manual de git). El gittutorial y su consiguiente documentación también están disponibles en línea aquí:

Para una documentación más completa de git, ver el libro "Pro Git": https://git-scm.com/book

Otro tutorial en línea que se ha recomendado es "Git for the Lazy": http://wiki.spheredev.org/Git_for_the_lazy

Mantén tus confirmaciones pequeñas y concretas. Cada commit debe aportar un cambio lógico al repositorio.

Mantén los mensajes de confirmación alrededor de 72 columnas de ancho (de modo que en un tamaño predeterminado de ventana de terminal, no se partan cuando se muestren con git log).

Usa la primera línea como un resumen de la intención del cambio (casi como la línea de asunto de un correo electrónico). Seguida por una línea en blanco, y luego un mensaje más largo explicando el cambio. Ejemplo:

Las correcciones de errores deben ir en la rama aplicable más antigua. Las nuevas funciones deberían ir a la rama master. Si no estás seguro a dónde pertenece un cambio, pregunta en el irc o en la lista de correo.

Cuando sea apropiado, organiza tus cambios en una rama (una serie de confirmaciones) donde cada commit es un paso lógico hacia su objetivo máximo. Por ejemplo, primero factoriza un código complejo en una nueva función. Luego, en una segunda confirmación, corrige algún error subyacente. Después, en un tercer commit agrega una nueva característica que se hizo más fácil por la refactorización y que no hubiera funcionado sin arreglar aquel error.

Esto es útil para los revisores, porque es más fácil ver que el paso "factorizar el código en una nueva función" era correcto, sin otras ediciones mezcladas; es más fácil ver que el error se corrige cuando el cambio que lo arregla es independiente de la nueva característica; y así sucesivamente.

Haz un esfuerzo por seguir el estilo de sangría predominante en el código circundante. En particular, los cambios en los espacios en blanco hacen que sea más difícil para otros desarrolladores rastrear cambios a lo largo del tiempo. Cuando se debe reformatear código, hazlo en una confirmación separada de cualquier cambio semántico.

La prueba "retval < 0" debería ser familiar; es el mismo tipo de prueba que se utiliza en el espacio de usuario (devuelve -1 para error) y en el espacio de kernel (devuelve -ERRNO para error).

Con git, es posible grabar cada edición y comienzo en falso en una confirmación separada. Esta es una forma muy conveniente de crear puntos de control durante el desarrollo, pero a menudo no querrás compartir estos comienzos en falso con otros.

Git proporciona dos formas principales de limpiar el historial, las cuales se pueden hacer libremente antes de compartir el cambio:

git commit --amend te permite hacer cambios adicionales a tu última confirmación, modificando opcionalmente también el mensaje de confirmación. Utiliza esto si te das cuenta de inmediato que dejaste algo fuera de la confirmación, o si cometiste un error tipográfico en el mensaje.

git rebase --interactive upstream-branch te permite volver a través de cada confirmación realizada desde que bifurcaste tu rama de características desde la rama superior, posiblemente editando, descartando o comprimiendo (combinando) commits con otros. Rebase también se puede usar para dividir confirmaciones individuales en múltiples confirmaciones nuevas.

Si tu cambio consta de varios parches, git rebase -i puede usarse para reordenarlos en una secuencia de confirmaciones que exponga más claramente los pasos de tu trabajo. Una consecuencia potencial de reordenar parches es que podrían aparecer dependencias incorrectas, por ejemplo, introducir el uso de una variable y, en un parche posterior, la declaración de esa variable.

Aunque la rama HEAD compile, no todas las confirmaciones podrían compilar en tal caso. Eso rompe git bisect, algo que alguien podría usar más tarde para encontrar la confirmación que introdujo un error. Así que más allá de asegurarte que tu rama compile, es importante asegurar que cada confirmación individual también compile.

Hay una forma automática de verificar que cada confirmación en una rama sea compilable - ver https://dustin.sallings.org/2010/03/28/git-test-sequence.html y el código en https://github.com/dustin/bindir/blob/master/git-test-sequence. Usarlo de la siguiente manera (en este caso probando cada confirmación desde origin/master a HEAD, incluida la ejecución de pruebas de regresión):

Esto informará que todo está bien (All is well) o que tronó (Broke on <confirmación>)

Utiliza la capacidad de cambiar el nombre de los archivos con mucho cuidado. Así como el indentar archivos individuales, los cambios de nombre hacen más difícil dar seguimiento a cambios en el tiempo. Como mínimo deberías buscar consenso, en IRC o en la lista de correo, de que el cambio de nombre es una mejora.

Utiliza git pull --rebase en lugar de un puro git pull para mantener un buen historial lineal. Cuando rebasas, siempre retienes tu trabajo como revisiones por delante de origin/master, por lo que puedes hacer cosas como git format-patch para compartirlo con otros sin hacer push al repositorio central.