Hacer Pull Requests en Hercules

[jaBote 438]

¡Vaya! Parece que hay gente deseosa de colaborar directamente con Hercules pero que no sabe cómo. Me parece estupendo. Además, a petición de los administradores, esta guía también tendrá una versión en inglés porque nuestros compañeros anglosajones así lo necesitan.

¿Recuerdan cuando en mi guía de cómo obtener Hercules les comenté que una gran ventaja de usar Git frente a usar Subversion (SVN) es que existe la posibilidad de participar de forma activa en la comunidad enviando pull requests? Pues aquí les traigo una guía detallada para que puedan hacer cuantos pull request quieran sin problema.

Ante todo, ¿qué es un pull request? Se trata de un envío de un cambio o mejora de un determinado proyecto a los desarrolladores del mismo, junto a la petición (request) de tal forma que ellos mismos puedan determinar y valorar si es conveniente para el proyecto y "tirar" (pull) de dicho cambio para que aparezca en el repositorio, o simplemente declinar la petición.

Git ofrece sus propias herramientas para hacer pull requests (más información), pero no serán estas herramientas las que usaremos (porque tampoco son compatibles), sino las que nos ofrece GitHub, que sirven para algo parecido pero es más visual y puede hacerse también desde cualquier plataforma.

¿Qué pasos hay que realizar para hacer un pull request a Hercules? Pues, a grandes rasgos, son los siguientes:

• [*]Registrar un usuario en

GitHub, si aún no tienes. [*]Hacer un fork (una "bifurcación" en la línea de desarrollo: generalmente se hacen para contribuir al proyecto original o decidir tomarlo como base para un futuro proyecto) de Hercules en GitHub, si aún no la hiciste. [*]Clonar el nuevo repositorio en nuestra máquina, si aún no lo tienes (no sirve trabajar en el repositorio original de HerculesWS). [*]Trabajar en el nuevo repositorio local. [*]"Enviar" (Commit) los cambios a nuestro repositorio local en el fork. [*]"Empujar" (Push) los cambios recién enviados a nuestro repositorio remoto en GitHub. [*]Hacer el propio pull request al repositorio original de Hercules, desde la web de GitHub.

Los pasos 3 y 5 se han visto en mi anterior guía sobre la obtención de Hercules (el paso 5 en la sección Preguntas Frecuentes), y el resto de pasos son suficientemente sencillos aunque se detallará exhaustivamente su realización. Se juntarán algunos apartados de la guía bajo un mismo epígrafe (3, 4, 5 y 6) para trabajar más cómodamente.

GitHub también provee sus propias guías paso a paso (en inglés) para casos generales sobre cómo hacer un fork y posteriormente hacer un pull request, aunque en la presente guía nos centraremos en hacer todo paso a paso para poder hacer pull requests a Hercules.

Para esta guía se usará la interfaz de TortoiseGit en inglés. Ya comenté en mi anterior guía lo poco adecuada que era la traducción de la interfaz al español, y además podré reutilizar las imágenes para la traducción de la presente guía al idioma anglosajón.

Bueno, comencemos ya con la propia guía. He decidido cubrir con spoilers cada paso de la guía, dado que además de su explicación vienen con sus buenas imágenes informativas.

Paso 1: Registrar un usuario en GitHub

Comencemos con algo bien sencillo: Registrar una cuenta de usuario en GitHub. Esto no tiene complicación: Simplemente se trata de acceder a la página en cuestión y saldrá un formulario que pide, por orden, nombre de usuario, correo electrónico y contraseña (debe tener al menos 7 caracteres y 1 dígito). Una vez rellenos los datos que se nos piden (se pueden poner datos falsos, aunque se recomienda que el correo sea válido si se piensa tener asiduidad), hacemos click en el botón verde "Sign up for free" (no necesitaremos pagar nada por usar GitHub siempre que colaboremos con proyectos de software libre como Hercules). Los datos introducidos para hacer esta guía son ficticios y están usados meramente como ejemplo.

 

Ya está, ya estamos registrados en GitHub. Se nos ofrece una serie de guías rápidas, en inglés, que nos pueden servir de documentación rápida, y a la que podremos acceder más tarde.

Paso 2: Hacer un fork de Hercules

Ahora necesitaremos hacer un fork de Hercules para poder trabajar con él de forma personal es bien sencillo. GitHub nos ofrece una sencilla (pero poderosa) herramienta para hacer forks. Simplemente con ir al repositorio original de Hercules con nuestro usuario registrado en esta web observamos varios botones arriba a la derecha, en especial uno llamado: Fork. Hacemos click en ese botón y se nos enviará a una pantalla en que se nos comunica que el fork está en proceso mediante una imagen de un libro sobre un escáner con un tenedor (fork en inglés ) clavado. Una vez termine el proceso tendremos nuestro fork terminado y acceso como dueño de nuestro fork. Observad bien el botón llamado Pull Request. Después haremos uso de él.

Prestad además especial atención a que el repositorio en que estamos trabajando ahora mismo tiene un nombre muy particular: estamos en Usuario_Github / Hercules y la url del repositorio será https://github.com/Usuario_Github/Hercules.git. Este es el repositorio con el que trabajaremos en los siguientes pasos (simplemente cambia Usuario_Github por el nombre de usuario con que te hayas registrado la web de GitHub.

Pasos 3 a 6: Trabajo en la máquina local

Este apartado completo se compone de varios pequeños pasos, todos hechos en nuestra máquina. En este apartado se incluyen la clonación de nuestro fork en la máquina local, el trabajo en el mismo, la realización del commit y hacer push al repositorio hospedado en GitHub. Tranquilo, no es para tanto, aunque esto ahora sí difiere un poco según el sistema operativo. Vayamos poco a poco:

Clonar el fork en la máquina local:
Se supone que tras haber obtenido Hercules satisfactoriamente sabes clonar un repositorio Git. ¿No te acuerdas? Revísala, en especial el apartado de cómo obtener y actualizar Hercules con un cliente Git.
 
El proceso es esencialmente el mismo, salvo que todo ha de hacerse en una nueva carpeta y no tienes que clonar el repositorio oficial de Hercules, sino el de tu fork de Hercules. ¿Y cuál es su URL? Puedes ir a tomarla en el repositorio de tu propio fork, aunque dicha URL siempre es de la forma: https://github.com/Usuario_Github/Hercules.git. Simplemente cambia Usuario_Github por el nombre de usuario con que te registraste en la la web de GitHub.

Trabajar en el repositorio casero:
Aquí nadie puede ayudarte. Si realmente quieres colaborar con el proyecto Hercules y tienes ideas que desarrollar, entonces quien debe hacer este trabajo eres tú, porque si supieramos cualquier mejora o modificación que debiéramos hacer al emulador, entonces no habría guía, ¿verdad?

Para esta guía se ha tomado como ejemplo de contribución una ligera modificación al archivo doc/script_commands.txt. Recuerda tener guardados todos los ficheros con los que vayas a trabajar.

Hacer un commit al repositorio local:
Una vez hayas terminado el trabajo en el emulador, tienes que enviar (commit, aunque TortoiseGit en español lo llama consignar) los cambios a tu repositorio local. ¡Exacto! No basta con simplemente guardar los cambios sino que además tienes que hacer constar el envío a tu repositorio local. Esto es una especie de doble confirmación, pero entre otros motivos se hace por seguridad. La forma de hacer el commit difiere según el sistema operativo. Como ya indiqué cómo hacer esto en las Preguntas Frecuentes de mi anterior guía (con otro propósito), me limito a copiar la parte interesante:

• [*]

Para Windows:

• [*]Haz click con el botón derecho en la carpeta donde tengas el repositorio local de Hercules y selecciona la opción

Git Commit -> "master" (Git Consignar -> "master" en español). [*]Si es la primera vez que envías datos a este repositorio Git (aunque sea a tu repositorio local), te saldrá una ventana de aviso que te pedirá un nombre de usuario y correo. Puedes ofrecer esa información (o incluso información falsa) a TortoiseGIT sin ningún problema. Haz click en Yes y rellena los campos de nombre y correo (Name y Email en inglés). No es necesario dar ningún ID de clave (Signing Key ID en inglés). Pulsa en Aceptar.

• Nota: Si no quieres que se te pregunte por un nombre de usuario y contraseña cada vez que trabajes en un nuevo proyecto, marca la opción Save as Global (Guardar como Global) antes de aceptar, o bien haz uso del botón Edit global .gitconfig (Editar .gitconfig global en español) e introduce ahí los datos que quieras.
  

[*]Saldrá una nueva ventana en que puedes poner un mensaje para tu envío. Su función es que puedas recordar fácilmente lo que hiciste, pero puedes omitirlo si quieres. Además hay otras opciones que no son interesantes a menos que vayas a hacer algo más avanzado. Haz click en OK para aceptar y espera a que termine el commit, el cual se producirá en una nueva ventana.

• [*]

Para sistemas Unix: Simplemente ejecuta el siguiente código desde la carpeta del repositorio local de nuestro fork (puedes editar el mensaje para tu envío si quieres):

git commit -am "Mensaje que será enviado junto a mis cambios :D"

Podemos además observar que una vez hecho el commit todos los archivos que hemos modificado se ven como si no hubieran sido cambiados. ¿Por qué? Muy sencillo, porque hemos creado nosotros una nueva revisión, la cual es solo para nosotros, y además ahora mismo estamos en su última revisión.
 
Hacer push de los cambios locales al repositorio en GitHub:
Ahora deberemos hacer un push del commit que acabamos de hacer localmente. ¿Qué significa hacer push? Pues simplemente es enviar los cambios que hemos hecho a nuestro repositorio público, para que allí se vean reflejados. De no hacerlo, nuestro fork en GitHub no se enterará jamás de lo que hemos hecho. ¿Y cómo hacerlo? Pues una vez más, la forma de hacerlo difiere según el sistema operativo:

• [*]

Para Windows:

1. Para hacer este primer paso hay dos posibilidades. La primera es usar la ventana del commit una vez éste ha terminado y hacer uso directo del botón Push... (en español, Empujar...) que aparece en dicha ventana, o bien hacer click derecho en la carpeta donde esté el repositorio en que estemos trabajando y seleccionar la opción Push... (Empujar...), dentro del menú desplegable que aparece al mantener el ratón unos instantes sobre la opción TortoiseGit. Ambas opciones funcionan de forma idéntica.
2. En la siguiente ventana podemos pulsar OK sin mayor preocupación, a menos que busquemos algo avanzado. Tras ello se iniciará el proceso de push, para el que se nos pedirá nombre de usuario y contraseña del repositorio en red (o sea, usuario y contraseña de nuestra cuenta en GitHub). Una vez correctamente indicadas las credenciales, la orden de push se hará efectiva y estaremos enviando nuestro trabajo directamente al repositorio que tenemos en GitHub. Por desgracia no podemos hacer el pull request usando el botón Create pull request (Crear solicitud para tirar en la increíblemente errónea traducción de la interfaz al español) que aparece en ella ya que hay que hacerlo en la web de GitHub, así que una vez hayamos esperado a que el push termine deberemos cerrar la ventana.
   

• [*]

Para sistemas Unix:  de nuevo es más sencillo hacer un push en Linux. En este caso, lo que hay que ejecutar desde la carpeta del repositorio local de nuestro fork es:

git push origin master

Al igual que en Windows, se te pedirán las credenciales de acceso, que debes proveer correctamente.

¡Listo! Ya hemos hecho un push a nuestro repositorio de GitHub. Sería buena idea comprobar que el push ha funcionado y que podemos ver nuestros cambios desde el repositorio en línea que tenemos en su web.

Paso 7: Hacer (por fin) el pull request

¡Ya va siendo hora de acabar todo esto! Solo queda un paso muy sencillo, y es volver a acceder a GitHub para hacer el pull request. Simplemente entra en la web y visita el repositorio de tu fork. ¿Recuerdas los botones que aparecían arriba a la derecha? Pues ya es hora de darle al botón llamado Pull Request. Serás enviado a una página en que deberás poner título y descripción a tu pull request (y a menos que sepas muy bien lo que haces no deberías tocar muchas más cosas). Intenta ser descriptivo (y escribe en inglés si puedes) para posteriormente hacer click en el botón verde Send Pull Request. Se te enviará de nuevo al repositorio original de Hercules para que puedas ver cómo se ha enviado tu pull request. El resto del proceso de aceptación o rechazo de tu contribución al código está en manos del equipo de desarrollo de Hercules.
 

 

 
 
Y ya está. No es tan complicado todo, ¿verdad? Esta pregunta parece irónica, pero es un proceso realmente simple. Una vez hayas hecho un par de pull requests verás que es un proceso increíblemente simple.

[jaBote 438]

Preguntas frecuentes:

He colocado la sección en otro post para facilitar su redacción y búsqueda.

Aunque espero que no haya prácticamente ninguna pregunta en esta sección porque me gustaría creer que he sido suficientemente claro, es obvio que las cosas no son así y es normal "atascarse" en alguna parte de la guía, inauguro esta sección. Como es usual en estas secciones de Preguntas y Respuestas, las preguntas las marcaré con una P y las respuestas las marcaré con una R, ambas bien grandes para que se vean en condiciones.

Lista de preguntas:

 

• [*]No puedo hacer

Pull Request en GitHub y me sale un mensaje de advertencia. ¿Qué ocurre? [*]¿Cómo actualizo mi fork a la última versión de Hercules? [*]Al intentar hacer push me sale un error aunque ponga las credenciales correctas. ¿Qué ocurre? [*]No puedo hacer commit a mi repositorio local. ¿Qué ocurre?

 
Preguntas y respuestas:

P: No puedo hacer Pull Request en Github y me sale un mensaje de advertencia. ¿Qué ocurre?
R: Vaya. Estos mensajes de advertencia siempre salen por algún motivo. No puedes hacer pull request mientras alguna advertencia esté activa. No soy un maestro en estos problemas, aunque generalmente los mensajes dan suficiente información en inglés. Estos son los mensajes de advertencia que me han llegado a salir a mí y las posibles soluciones de que dispongo. Recordad que en cualquier caso deberéis cambiar HerculesUser por vuestro nombre de usuario:

• [*]

Oops! HerculesWS:master  is already up-to-date with HerculesUser:master  Try a different branch?

• [*]Has intentado hacer

pull request sin haber hecho algún cambio frente al repositorio original en tu fork. Asegúrate de haber hecho push (con al menos algo de contenido) correctamente a tu repositorio en GitHub.

[*]Oops! There's already a pull request for HerculesUser:master Try a different branch or view the pull request?

• [*]Ya tienes un

pull request activo en el proyecto al que intentas contribuir. Espera a que sea aceptado o rechazado, o si quieres añadir más cosas mientras dicho pull request está activo siempre puedes cancelar la petición, añadir tu nuevo trabajo y volver a hacer pull request.

P: ¿Cómo actualizo mi fork a la última versión de Hercules?
R: Es bastante sencillo, aunque menos directo que actualizar una versión de Hercules directamente obtenida del repositorio original. Como siempre, para esto es necesario hacer distinción de cómo se haría en cada sistema operativo:

• Para Windows: (No veo necesaria una imagen a menos que mucha gente se atasque aquí)
  1. Haz click derecho en la carpeta de tu fork de Hercules y selecciona la opción Fetch... (Recuperar... en la interfaz española) dentro del menú desplegable que aparece al mantener el puntero del ratón unos instantes sobre la opción TortoiseGit.
  2. Se abrirá una nueva ventana. En esa ventana debemos escoger la opción que nos permite indicar una URL arbitraria (Arbitrary URL) y en el campo de texto asociado, colocar la URL del repositorio original de Hercules, o sea, esta: https://github.com/HerculesWS/Hercules.git. Posteriormente hacemos click en OK (a menos que quieras cambiar alguna de las opciones disponibles, que no es frecuente) para que empiece la actualización.
  3. Se abrirá una ventana en la que empezará la actualización de tu fork. Ciérrala una vez hayas acabado.
     

  [*]Para sistemas Unix: Como siempre, se trata simplemente de ejecutar un único comando (aunque esta vez son dos comandos unidos en una misma orden de shell):

  git fetch upstream && git merge upstream/master

   

  
  

Simplemente recuerda que para que esta actualización también se refleje en tu repositorio hospedado en GitHub has de hacer push. En caso contrario solo se reflejará en el repositorio local.

 

P: Al intentar hacer push me sale un error aunque ponga las credenciales correctas. ¿Qué ocurre?
R: A mí hasta ahora solo me ha ocurrido este error cuando por accidente intenté hacer push en la carpeta que tenía del repositorio original de Hercules, sobre el que no tengo permisos de escritura. Asegúrate de que estás haciendo push al repositorio de tu fork de Hercules y no al original: si no jamás lograrás hacerlo con éxito.

 

¡Ah, por cierto! Aunque esto es de sentido común, para hacer push y actualizar tu repositorio hospedado en GitHub es obligatorio disponer de conexión a Internet en el momento en que se intente efectuar.
 

P: No puedo hacer commit a mi repositorio local. ¿Qué ocurre?
R: Lo más seguro es que intentes hacer un commit a tu repositorio local sin haber modificado ningún archivo. No es posible hacer commits vacíos, así que el fallo estará por alguna otra parte. ¿Quizá modificaste los archivos a los que fueras a hacer commit pero se te olvidó guardarlos?