Introducción a GitHub

Esta lección cubre los conceptos básicos de GitHub, una plataforma para alojar y administrar cambios en tu código.

Dibujo de Tomomi Imura

Cuestionario previo a la clase

Introducción

En esta lección, cubriremos:

Seguimiento de trabajo que se realiza en su máquina.
Trabajar en proyectos con otros.
Cómo contribuir al software de código abierto (Open Source)

Prerrequisitos

Antes de comenzar, debemos verificar si Git está instalado. Escribe en tu terminal: git --version

Si Git no está instalado, descargue Git desde aquí. Luego, configure su perfil de Git local en la terminal: git config --global user.name "tu-nombre" git config --global user.email "tu-email"

Para comprobar si Git ya está configurado, escribe: git config --list

También necesitarás una cuenta de GitHub, un editor de código (como Visual Studio Code) una terminal (también conocida como línea de comandos o símbolo del sistema).

Ve a GitHub.com y crea una cuenta si aún no lo has hecho, o inicia sesión y completa tu perfil.

✅ GitHub no es el único lugar para almacenar código; hay otros, pero GitHub es el más conocido.

Preparación

Necesitarás un directorio con un proyecto de código en tu máquina local (computadora portátil o PC) y un repositorio público en GitHub, que te servirá como ejemplo de cómo contribuir a los proyectos de otros.

Gestión de código

Digamos que tienes una directorio local con algún proyecto de código y deseas rastrear tu progreso usando git (sistema de control de versiones). Algunas personas comparan el uso de git con escribir una carta de amor a tu futuro. Al leer tus mensajes de confirmación días, semanas o meses después, podrás recordar por qué tomaste una decisión o "revertiste" un cambio, siempre y cuando escribas buenos mensajes a la hora de enviar un commit.

Tarea: Hacer un repositorio git y enviar código

Revisa este video

Crear repositorio en GitHub. En GitHub.com, en la pestaña de repositorios, o en la barra de navegación superior derecha, busca el botón nuevo repositorio.
1. Dale un nombre a tu repositorio (directorio)
2. Selecciona Crear Repositorio.
Navegue a su directorio de trabajo. En su terminal, navegue hasta el directorio donde tiene su proyecto que deseas comenzar a rastrear. Escribe:

   cd [nombre de su directorio]

Inicializar un repositorio de git. En su proyecto escribe:

   git init

Comprobar estado. Para comprobar el estado del proyecto escribe:

   git status

La respuesta de la terminal (CLI) probablemente se verá así:

   Changes not staged for commit:
   (use "git add <file>..." to update what will be committed)
   (use "git checkout -- <file>..." to discard changes in working directory)

        modified:   file.txt
        modified:   file2.txt

Por lo general, el comando git status nos avisa qué archivos están listos para ser guardados en el repositorio o cambios en tu codigo que puedes conservar.

Agregar archivos al seguimiento

   git add .

El comando git add más . indica que todos tus archivos y cambios están listos para darles seguimiento.

Agregar archivos puntuales

   git add [nombre de archivo o carpeta]

Esto nos ayuda a agregar solo los archivos seleccionados al área de preparación cuando no queremos confirmar todos los archivos a la vez.

Eliminar archivos de la zona de staging

   git reset

Este comando nos ayuda a eliminar todos los archivos a la vez.

Quitar un archivo en particular

   git reset [nombre del archivo o carpeta]

Este comando nos ayuda a eliminar un archivo/directorio puntual, para que éste no sea enviado en el próximo commit.

Persistir en tu trabajo. En este punto, has agregado los archivos a lo que se denomina stagin area. Un lugar donde Git rastrea tus archivos. Para que el cambio sea permanente, debes realizar un commit. Para hacerlo, utilizas el siguiente commando git commit. Un commit representa un punto en el historial de tu repositorio que estás guardando, este viene acompañado de un mensaje, el cual nos sirve para saber que cambios se hicieron dentro de ese commit. Ejecuta el siguiente comando para realizar tu primer commit.

   git commit -m "first commit"

Esto confirma todos tus archivos, agregando el mensaje "first commit". Para futuros mensajes de confirmación, querrás ser más descriptivo en tu descripción para transmitir qué tipo de cambio has realizado.

Conecta tu repositorio de Git local con GitHub. Es bueno tener un repositorio de Git en tu máquina, pero también tienes que guardar todos estos archivos en algún lugar e invitar a otras personas a trabajar contigo en tu repositorio. Un buen lugar para hacerlo es GitHub. Recuerda que ya hemos creado un repositorio en GitHub, por lo que lo único que debemos hacer es conectar nuestro repositorio de Git local con GitHub. El comando git remote add hará precisamente eso. Escribe el siguiente comando:

Nota, antes de escribir el comando, ve a la página de tu repositorio de GitHub para encontrar el URL del repositorio. Lo usarás en el siguiente comando. Reemplaza repository_name con tu URL de GitHub.

   git remote add origin https://github.com/USUARIO/NOMBRE_DEL_REPOSITORIO.git

Esto crea un remote, o conexión, llamado "origin" que apunta al repositorio de GitHub que creaste anteriormente.

Si tienes una conexión previa con algún "origin" y deseas cambiar la dirección puedes utilizar el siguiente comando:

   git remote set-url https://github.com/USUARIO/NOMBRE DEL REPOSITORIO.git

Envía archivos locales a GitHub. Hasta ahora ha creado una conexión entre el repositorio local y el repositorio de GitHub. Enviemos estos archivos a GitHub con el siguiente comando git push, así:

   git push -u origin main

Esto envía una confirmación en tu rama "main" en GitHub.

Para agregar más cambios. Si deseas continuar haciendo cambios y enviarlos a GitHub, solo necesitas usar los siguientes tres comandos:

   git add .
   git commit -m "escribe tu mensaje de confirmación aquí"
   git push

Sugerencia: es posible que también desees adoptar un archivo .gitignore para evitar que los archivos que no deseas rastrear aparezcan en GitHub. Puedes encontrar plantillas para archivos .gitignore en .gitignore templates.

Confirmar mensajes

Una buena línea de asunto (subject line), completa la siguiente frase: "Si se aplica, este commit hará..."

Para el asunto use el imperativo, tiempo presente: "cambiar" no "cambió" ni "cambiará". Como en el asunto, en el cuerpo (opcional) también use el presente imperativo. El cuerpo debe incluir el motivo del cambio y contrastarlo con el funcionamiento previo. Estás explicando el "por qué", no el "cómo".

✅ Tómate unos minutos para navegar por GitHub. ¿Puedes encontrar un mensaje de commit realmente bueno? ¿Puedes hallar uno aún más simple? ¿Qué información crees que es la más importante y útil de transmitir en un mensaje de commit?

Tarea: Colaborar

La razón principal para poner cosas en GitHub fue hacer posible la colaboración con otros desarrolladores.

Trabajando en proyectos con otros

Revisa este video

En tu repositorio, ve a Insights > Community para ver cómo se compara tu proyecto con los estándares comunitarios recomendados.

Aquí hay algunas cosas que pueden mejorar tu repositorio de GitHub:

Descripción. ¿Agregaste una descripción para tu proyecto?
README. ¿Agregaste un archivo README? GitHub proporciona una guía para escribir un README.
Guía de contribución. ¿Tiene guías de contribución tu proyecto?
Código de Conducta. Crea un Código de conducta.
Licencia. Quizás lo más importante, una licencia.

Todos estos recursos beneficiarán la incorporación de nuevos miembros del equipo. Y esos son típicamente el tipo de cosas que los nuevos colaboradores miran antes incluso de mirar tu código, para descubrir si tu proyecto es el lugar adecuado para que ellos pasen su tiempo.

✅ Los archivos README, aunque requieren tiempo para prepararse, a menudo son descuidados por los mantenedores. ¿Puedes encontrar un ejemplo de uno particularmente descriptivo? Nota: aquí hay algunas herramientas para ayudar a crear buenos archivos READMEs que te puedes probar.

Tarea: Fusionar (merging) código

Los documentos de contribución ayudan a las personas a contribuir al proyecto. Explica qué tipos de contribuciones estás buscando y cómo funciona el proceso. Los colaboradores deberán seguir una serie de pasos para poder contribuir a tu repositorio en GitHub:

Bifurcando (forking) tu repositorio Probablemente querrás que la gente bifurque (fork) tu proyecto. Bifurcar significa crear una réplica de tu repositorio en su perfil de GitHub.
Clonar. Desde allí, clonarán el proyecto en su máquina local.
Crear una rama. Querrás pedirles que creen una rama para su trabajo.
Concentre su cambio en un área. Pida a los colaboradores que concentren sus contribuciones en una cosa a la vez; de esa manera, las posibilidades de fusionar su trabajo son mayores. Imagínate que escriben una corrección de errores, agregan una nueva función y actualizan varias pruebas; ¿qué sucede si quieres todos los cambios o solo puedes implementar 2 de 3 ó 1 de 3 cambios?

✅ Imagínate una situación en la que las ramas (branches) de git son particularmente críticas para escribir y enviar buen código. ¿Qué casos de uso se te ocurren?

Sé el cambio que deseas ver en el mundo y crea también ramas para tu propio trabajo. Todos los commits que hagas se realizarán en la rama en la que estás actualmente "registrado". Usa git status para ver qué rama es.

Repasemos el flujo de trabajo de un colaborador. Supongamos que el colaborador ya ha bifurcado y clonado el repositorio para que tenga un repositorio de Git listo para trabajar en su máquina local:

Crea una rama. Usa el comando git branch para crear una rama que tendrá los cambios que quieres contribuir:

   git branch [branch-name]

Cambiar a rama de trabajo. Cambia a la rama especificada y actualiza tu directorio de trabajo con git switch:

   git switch [branch-name]

Trabaja. En este punto, deseas agregar tus cambios. No olvides informarle a Git con los siguientes comandos:

   git add .
   git commit -m "mis cambios"

Asegúrate de darle un buen nombre a tu commit, tanto por tu bien como por el del mantenedor del repositorio en el que estás ayudando.

Combina tu trabajo con la rama principal. En algún momento has terminado de trabajar y deseas combinar tu trabajo con el de la rama principal. La rama main podría haber cambiado mientras tanto, así que asegúrate de actualizarla con los siguientes comandos:

   git switch main
   git pull

En este punto, querrás asegurarte de que cualquier conflicto, situaciones en las que Git no pueda combinarse fácilmente los cambios, ocurran en tu rama de trabajo. Por lo tanto, ejecuta los siguientes comandos:

   git switch [branch_name]
   git merge main

Esto traerá todos los cambios de main a su rama y es de esperar que pueda continuar. De lo contrario, VS Code le dirá dónde está confundido Git y simplemente modificará los archivos afectados para decir qué contenido es el más preciso.

Envía tu trabajo a GitHub. Enviar tu trabajo a GitHub significa dos cosas. Empujar tu rama a tu repositorio y luego abrir un PR (Pull Request).

   git push --set-upstream origin [branch-name]

El comando anterior crea la rama en tu repositorio bifurcado.

Abre un Pull Request. A continuación, abre un PR. Para hacerlo, navega al repositorio bifurcado en GitHub. Verás una indicación en GitHub donde te preguntarán si deseas crear un nuevo PR. Haz clic allí y te llevará a una interfaz donde puedes cambiar el título del mensaje de commit, asígnale una descripción más adecuada. Ahora, el mantenedor del repositorio que bifurcaste verá esta PR y dedos cruzados valorarán y fusionarán tu PR. Ahora eres un colaborador, ¡yay! :)
Limpiar. Se considera una buena práctica "limpiar" después de que tu Pull Request fue combinado a la rama principal exitosamente. Limpia tanto tu rama local como la rama que enviaste a GitHub. Primero eliminémoslo localmente con el siguiente comando:

   git branch -d [branch-name]

Asegúrate de ir a la página de GitHub del repositorio bifurcado a continuación y elimina la rama remota que acabas de ingresar.

Solicitud de extracción (Pull request) parece un término tonto porque realmente deseas impulsar los cambios al proyecto. Pero el mantenedor (propietario del proyecto) o el equipo central debe considerar tus cambios antes de fusionarlo con la rama "principal" del proyecto, por lo que realmente estás solicitando una decisión de cambio a un mantenedor.

Una Pull request es el lugar para comparar y discutir las diferencias introducidas en una rama con revisiones, comentarios, pruebas integradas y más. Una buena Pull request sigue aproximadamente las mismas reglas que un mensaje de commit. Puedes agregar una referencia a un problema (issue) en el rastreador de problemas, cuando tu trabajo, por ejemplo, soluciona un problema. Esto se hace usando un '#' seguido del número de tu problema. Por ejemplo, #97.

🤞 Cruza los dedos para que todos los controles pasen y los propietarios del proyecto combinen tus cambios en el proyecto🤞

Actualiza tu rama de trabajo local actual con todas las nuevas confirmaciones de la rama remota correspondiente en GitHub:

git pull

Cómo contribuir al código abierto

Primero, busquemos un repositorio en GitHub que te interese y al que te gustaría contribuir con un cambio. Querrás copiar el contenido a nuestra máquina.

✅ Una buena forma de encontrar repositorios 'aptos para principiantes' es buscar por la etiqueta good-first-issue.

Hay varias formas de copiar código. Una forma es "clonar" el contenido del repositorio, usando HTTPS, SSH o usando GitHub CLI (Interfaz de línea de comandos).

Abre tu terminal y clona el repositorio así: git clone https://github.com/ProjectURL

Para trabajar en el proyecto, cambia al directorio correcto: cd ProjectURL

También puedes abrir todo el proyecto utilizando Codespaces, el entorno de desarrollo en la nube / editor de código integrado de GitHub o GitHub Desktop.

Por último, puedes descargar el código en un directorio comprimido.

Algunas cosas más interesantes sobre GitHub

Puedes destacar, ver y/o hacer "fork" cualquier repositorio público en GitHub. Asimismo, encontrar tus repositorios destacados en el menú desplegable de la parte superior derecha. Es como marcar como favorito, pero por código.

Los proyectos tienen un rastreador de problemas, principalmente en GitHub en la pestaña "Issues" a menos que se indique lo contrario, donde las personas debaten los problemas relacionados con el proyecto. Y la pestaña Pull requests es donde las personas debaten y revisan los cambios que están en curso.

Los proyectos también pueden tener discusiones en foros, listas de correo o canales de chat como Slack, Discord o IRC.

✅ Echa un vistazo a tu nuevo repositorio de GitHub y prueba algunas cosas, como editar la configuración, agregar información a tu repositorio y crear un proyecto (como un tablero Kanban). ¡Hay muchas cosas que puedes hacer!

🚀 Reto

Reúnete con un amigo para trabajar en el código del otro. Crea un proyecto en colaboración, haz fork del código, crea ramas y hagan merge a los cambios.