-
Notifications
You must be signed in to change notification settings - Fork 90
2. GitHub: Construyendo ciudadanía un commit a la vez
Ok, ya nos hemos registrado a GitHub, ¿qué se hace ahora? Hay muchas opciones, botones, íconos y mensajes que pueden parecer abrumadores, pero no te preocupes iremos viendo cada uno de ellos.
GitHub es en esencia una plataforma de desarrollo de software, pero en realidad es mucho más que eso, ya que nos permite aprender nuevas habilidades a través de otros usuarios, también podemos colaborar en software y proyectos de todo tipo e incluso crear comunidades e impulsar iniciativas a gran escala. Sin mencionar que GitHub cuenta con más de 28 millones de repositorios públicos, lo que lo convierte en la mayor plataforma de código abierto del mundo.
Una manera de saber que se está creando en GitHub es echando un vistaso en github.com/explore, en donde puedes encontrar proyectos, eventos, tutoriales y más en todas la áreas del conocimiento como gobierno, periodismo, inteligencia artificial o soluciones a problemas específicos como visualizaciones de datos, entre muchas cosas más.
¿Y por qué estamos usando esta plataforma para aprender hacking cívico? Usar GitHub nos permite compartir código, tener conversaciones y consultar recursos de la misma manera que lo hacen millones de personas de todo el mundo, así cuando queramos incursionar en alguna iniciativa, ya sabremos hacerlo.
Primero veamos un poco de la tecnología en la que se basa GitHub, la cual se llama Git. Al igual que cuando trabajamos en un documento importante en nuestra máquina local y este requiere de muchas modificaciones a lo largo del tiempo en donde terminamos creando muchas copias hasta terminar con nombres como documento_final_final_3.docx o algo por el estilo, el mismo problema surge cuando trabajamos con código. Para documentos de texto existen soluciones en la nube como Google Docs que guardan los cambios automáticamente por ti y te permiten revisar este historial de cambios, sin embargo nos nos deja decidir exactamente qué y cuándo queremos que se guarde. Este nivel de control si es necesario cuando estamos programando, especialmente en proyectos en donde colaboramos con más de una persona, por lo que se necesita una herramienta un poco más adecuada.
Aquí es donde entra Git, un sistema de control de versiones, que guarda el historial de cambios a medida que las personas y los equipos colaboran en proyectos de manera conjunta. A medida que un proyecto evoluciona, los equipos pueden ejecutar pruebas, corregir errores y contribuir con código con la confianza de que cualquier versión se puede recuperar en cualquier momento. Los desarrolladores pueden revisar el historial del proyecto para descubrir:
- ¿Qué cambios se hicieron?
- ¿Quién hizo los cambios?
- ¿Cuándo se hicieron los cambios?
Ver un historial transparente de cambios, quién los hizo y cómo contribuyen al desarrollo de un proyecto ayuda a los miembros del equipo a mantenerse alineados mientras trabajan de forma independiente.
Sin un sistema de control de versiones, muchas de las tareas serían redundantes, plazos más lentos y tendríamos múltiples copias de un solo proyecto que no están sincronizadas. Para eliminar el trabajo innecesario, Git y otros sistemas de control de versiones brindan a cada contribuidor de código una visión unificada y coherente de un proyecto, que muestra el trabajo que ya está en progreso.
Más del 70 por ciento de los desarrolladores usan Git, lo que lo convierte en el sistema de control de versiones más utilizado en el mundo. Git se usa comúnmente para el desarrollo de software comercial y de código abierto, y sirve tanto para individuos, equipos y empresas.
El uso y todas las funciones que provee git están fuera del alcance de este curso, pero puedes exite una gran cantidad de recursos en internet que podrás consultar.
GitHub integra la colaboración directamente sobre esta tecnología. El trabajo se organiza en repositorios, donde se puede trabajar en equipo directamente en la nube, integrando también muchas otras aplicaciones que los desarrolladores usan para crear un flujo de trabajo eficiente.
Un repositorio es un espacio que se usa generalmente para organizar un proyecto. Los repositorios pueden contener archivos de código, imágenes, carpetas, documentos, conjuntos de datos y cualquier cosa que el proyecto necesite junto con el historial de cada uno de estos archivos.
Trabajar en repositorios mantiene los proyectos organizados y protegidos. Alienta a los desarrolladores a corregir errores o crear nuevas funciones, sin miedo a deshacer los esfuerzos de otros colaboradores.
Para crear un nuevo repositorio, nos iremos a la página principal de GitHub:
- Del lado derecho podemos dar clic en el botón verde, o en la esquina superior derecha, al lado de nuestro avatar, hacemos clic y luego seleccionamos Nuevo repositorio.
- Lo primero que nos pedirá, será darle un nombre, le pondremos
hola-mundo, haciendo referencia a la famosa frase que se utiliza cuando aprendemos a programar. - Opcionalmente podemos agregar una breve descripción y escoger si queremos que el repositorio sea público o privado.
- Usualmente cuando empezamos desde cero, es buena idea empezar aunque sea con un archivo dentro del repositorio. Para esto seleccionamos la casilla que dice: Inicializar este repositorio con un archivo README.
El archivo README, es un archivo con información sobre el proyecto (parecido a un archivo de texto simple que sirve de documentación). GitHub facilita agregar uno al mismo tiempo que crea su nuevo repositorio. También ofrece otras opciones comunes, como un archivo de licencia, pero eso lo veremos más adelante.
- Hacemos clic en Crear repositorio.
Y listo, el repositorio de hola-mundo puede ser un lugar donde almacenar ideas, recursos o incluso compartir y discutir cosas con otros.
En Git y GitHub, el historial de cambios guardados aparece como puntos en el tiempo llamados commits, es un concepto parecido a los checkpoints en los videojuegos, en donde después de cierto avance creamos un punto de guardado al que podemos regresar en cualquier momento, nosotros podemos decidir qué archivos y qué tan seguido crear estos puntos de guardado o commits.
Cada commit es único e identificable a través de un hash y tiene un mensaje de confirmación asociado, que es una descripción que explica por qué se realizó un cambio en particular. Los mensajes de cada commit capturan el historial de los cambios para que otros colaboradores puedan entender lo que se ha hecho y por qué. Un proyecto en GitHub se puede organizar en múltiples líneas de desarrollo llamadas ramas, las cuales veremos más adelante.
Bien, ahora veamos como realizar cambios y crear commits:
- Para esto vamos a modificar el archivo
README.mddel repositorio que creamos. - Hacemos clic en el ícono de lápiz en la esquina superior derecha de la vista del archivo para editar.
- Se abrirá un editor de texto, en el podemos modificar el contenido del archivo, escribiendo por ejemplo más detalles sobre el repositorio como el autor o la fecha.
- Una vez que hayamos terminado de modificar el texto en la parte del
commitagregamos una descripción corta que explique los cambios que acabamos de realizar, es este caso nos da una sugerencia pero yo pondré algo más explícito como: Añadí información adicional. También podemos poner una descripción más completa en la parte de abajo si así lo queremos. - Por último hacemos clic en el botón commit changes.
Para consultar este historial de cambios podemos irnos a nuestro repositorio y dar clic en la parte superior derecha donde el número de commits. Una vez aquí podemos ver aquí en orden cronológico del más reciente al más antiguo. Si damos clic en uno de ellos podemos ver más a detalle los cambios que se realizaron.
Todo esto está sucediendo en una única línea temporal del proyecto, pero a veces necesitamos crear líneas alternas que nos permitan experimentar, hacer cambios o corregir errores sin afectar nuestra línea principal. Para esto entra el concepto de ramas o branches.
La ramificación es la forma de trabajar en diferentes versiones de un repositorio a la vez. Por defecto, los repositorios tienen una rama llamada master que se considera la rama default. Usualmente creamos ramas para hacer ediciones que posteriormente queremos integrar en la rama principal o rama master .
Cuando se crea una nueva rama a partir de la rama principal, se está haciendo una copia idéntica a como se encuentra el repositorio en ese momento, sin embargo, mientras trabajamos en esta nueva rama, no se mantendrá actualizada si se producen nuevos cambios en la rama principal, esto se tiene que hacer de manera manual usando git.
Aquí en GitHub, podemos ver las ramas del lado superior izquierda, al dar clic se desplegará un menú, en el podemos ver que solo tenemos la rama master como default.
Para crear una nueva rama:
- Simplemente escribimos el nombre que le queramos dar a la nueva rama en el cuadro de texto
- Y seleccione el cuadro de Crear rama o presionando "Enter" en el teclado.
Ahora tenemos dos ramas, la principal y otros cambios. Si cambiamos entre ellas podemos darnos cuenta de que ¡se ven exactamente iguales, pero no por mucho tiempo! A continuación, agregaremos cambios a la nueva rama.
Estos cambios consistirán en:
- Modificar otra vez el archivo README pero ahora en la rama de “otros-cambios”, siguiendo el mismo proceso que antes, no vamos al editor de texto y ahora cambiaremos el título y la descripción.
- Ahora agregaremos un nuevo archivo, para esto tenemos 2 opciones
- La primera es cargarlo desde nuestra computadora, ya sea arrastrándolo o seleccionándolo desde nuestro explorador de archivos. Escribimos en mensaje del
commity lo guardamos. - La segunda es creando un archivo, este solo puede ser un archivo de código o texto en donde tenemos que poner el nombre y la extensión del mismo.
Si nos vamos al historial de los commits podemos ver los cambios que hemos hecho en el repositorio bajo esta nueva rama. GitHub nos indica que estamos varios commits o cambios guardados adelante de la rama master, para integrar estos cambios veremos lo que es un Pull Request.
Ahora que tenemos estos cambios en una rama fuera de la rama master, podemos abrir un Pull Request. GitHub automáticamente nos pone la opción de crearlo o nos podemos ir a la sección de Pull request y crear uno a partir de la comparación de 2 ramas, en este caso nuestra rama “otros cambios” y “master” y le damos crear.
Los Pull Requests son el corazón de la colaboración en GitHub, cuando abrimos un Pull Request, estamos proponiendo cambios para que potencialmente alguien más revise e integre nuestra contribución con la rama principal. Los Pull requests muestran diferencias o cambios del contenido de ambas ramas comparándolas entre sí.
Esta manera de trabajar es más útil cuando estamos colaborando con más personas en un solo proyecto, ya que podemos solicitar que alguien más revise los cambios y los apruebe o podemos usar la sección de comentarios para pedir alguna corrección o discutir la contribución. Podemos usar el @ para mencionar a otro usuario que esté colaborando.
Es una excelente manera de aprender el flujo de GitHub antes de trabajar en proyectos más grandes.
Ahora el paso final, es hora de unir los cambios, fusionando la rama de otras ediciones con la rama master. Para esto:
- Hacemos clic en el botón verde dentro del
Pull Requestque dice “Merge” para fusionar los cambios. - Hacemos clic para Confirmar el merge.
- Una vez que los cambios han sido incorporados a la rama principal, podemos eliminar la nueva rama con el botón
Eliminarrama en el cuadro morado, ya que usualmente no la volveremos a usar, si queremos volver a proponer cambios es mejor crear una nueva rama y repetir el proceso.
Bien con esto haz logrado:
- Crear un repositorio de código abierto.
- Guardar cambios y ver el historial del repositorio.
- Crear y modificar una nueva rama.
- Abrir e integrar esta rama con un Pull Request.
Ahora, ¿cómo podemos agregar a otras personas para que colaboren dentro de nuestro repositorio? Ya sea que nuestro repositorio esté público o privado, para que otras personas tengan los permisos necesarios para modificar o agregar cosas nos tenemos que ir a nuestra configuración del repositorio, en el apartado de manejo de acceso y aquí añadimos y cambiamos los roles de las personas con acceso. podemos agregar a un colaborador a través de su usuario, email o nombre.
Esto nos es muy útil cuando estamos trabajando en un proyecto personal o con un equipo definido, pero es posible que deseemos contribuir al proyecto o iniciativa de otra persona. O tal vez le gustaría utilizar el proyecto de alguien más como punto de partida para el nuestro. Este proceso se conoce como bifurcación o Fork.
Crear un Fork es producir una copia personal del proyecto de otra persona. Los forks actúan como una especie de puente entre el repositorio original y su copia personal.
Podemos también enviar Pull Requests para ayudar a mejorar los proyectos de otras personas mandando nuestros cambios hasta el proyecto original. Forking es el núcleo de la codificación social en GitHub.
Para este ejemplo, utilizaremos el proyecto Spoon-Knife, el cual es un repositorio de prueba creado por GitHub que nos permitirá ver como es el flujo de trabajo de los Pull Requests en desde un Fork. El nombre de este repositorio hace referencia a referencia los cubiertos que acompañan al Fork o “tenedor”, la cuchara y cuchillo si lo traducimos literalmente aunque una traducción más adecuada de Fork sería el término “bifurcación”.
octocat/Spoon-Knife: This repo is for demonstration purposes only.
Para esto nos vamos primero a esta dirección, en donde encontraremos el repositorio de prueba, para hacer un Fork del repositorio, hacemos clic en el botón en la parte superior derecha en el encabezado. Y esperamos un momento en lo que se hace la copia del repositorio en nuestra cuenta. Cuando termine, nos llevará automáticamente a nuestra copia de Spoon-Knife.
Ok, muy bien ahora si veamos un poco de lo que contiene el repositorio, podemos ver que contiene 3 archivos y también nos encontramos con 3 ramas, también podemos consultar el historial de commits.
Realizaremos algunos cambios en el proyecto, por ejemplo a este archivo README no le vendría mal unos emojis, podemos crear una nueva rama o hacerlo directamente en la rama master ya que esto no afectará al repositorio original. Pero practicar un poco, crearé una nueva rama llamada “emojis”.
Utilizando el editor de GitHub empezaré a modificar el contenido de este archivo. Podemos ver que el texto tiene algunos elementos que le dan formato, este lenguaje se llama Markdown, pero lo veremos más adelante, por ahora solo agregaremos un par de emojis. Cuando hayamos terminado guardamos los cambios haciendo un commit.
Listo, para proponer estos cambios en el proyecto original abriremos un Pull Request dando click en el mensaje que nos aparece. Si bien ya habíamos hecho Pull Requests dentro de nuestro mismo repositorio anteriormente, el verdadero valor es cuando los usamos para proponer cambios en el repositorio de alguien más.
Podemos ver que automáticamente hace la comparación entre la rama master del repositorio original y la rama emojis de nuestra copia, pero si damos clic aquí podemos cambiar el repositorio al que queremos mandar los cambios, este puede ser el nuestro o también nos muestra todas las copias que han hecho otras personas. Dejaremos el repositorio original y daremos clic en crear Pull Request.
Nos redirige al proyecto principal en donde hemos abierto exitosamente una solicitud para contribuir a través de un Pull Request, de hecho si nos vamos a la sección de Pull Requests podemos ver todos los que han mandado otras personas, que en este caso son muchos ya que es un repositorio muy popular para aprender a usar GitHub. Ya dependerá del dueño de este repositorio aceptar o rechazar nuestros cambios.
Si bien este es un ejemplo un poco burdo, es exactamente el mismo proceso el que se sigue cuando se construye un proyecto de código abierto, donde podemos contribuir desde corregir algún error ortográfico en la documentación del proyecto de un amigo, hasta agregar nuevas funcionalidades a un software que usan millones de personas.
Como te habrás dado cuenta, hemos utilizado algunas de las secciones de un repositorio pero no hemos explorado todas aún. Lo siguiente que veremos será la sección de Issues.
Los “Issues” son una excelente manera de realizar un seguimiento de las tareas de nuestros proyectos. Es parecido a un foro en donde se puede compartir y discutir con el resto del equipo. La mayoría de los proyectos de software tienen algún lugar para rastrear de errores, proponer mejoras o discutir cambios, en GitHub esta es la sección de Issues y cada repositorio cuenta con esta sección.
Crear un Issue
Bien ahora veamos un ejemplo de como crear un Issue, nos vamos a la sección correspondiente y le damos clic en crear nuevo Issue. Veremos que tenemos varias opciones. Lo primero es agregar un título y una descripción sobre qué se trata el Issue.
Asignar personas
Podemos asignar a alguien para que los revise, cada Issue puede tener una o varias personas responsables de resolver el tema.
Etiquetas
Podemos agregar etiquetas que nos ayudan a clasificar y filtrar los Issues y son una excelente manera de organizar diferentes tipos de Issues. Los Issues pueden tener tantas etiquetas como deseemos. Hay varias por defecto pero siempre podemos agregar y personalizar nuevas.
Milestones
Los Milestones o hitos es una manera de agrupar Issues que comúnmente corresponden a una etapa de un proyecto, característica o período de tiempo. Pero en realidad se puedes usar de cualquier manera para agrupar Issues.
Notificaciones
Podemos modificar también las preferencias de las notificaciones.
Comentarios
Los comentarios permiten que otras personas nos brinden retroalimentación. Podemos usar menciones con un arrob@ y podemos incluso hacer referencias a otros Issues, ya que cada que abrimos uno, se le asigna un número así como este el primero, podemos usar el hastag para mencionar cualquier otro.
Si exploramos algún otro repositorio público en donde muchas personas colabores podremos ver todas las conversaciones que se están llevando a cabo en ese proyecto.
Otra de las secciones con las que contamos en cada repositorio es la sección de proyectos, la cual es una manera de organizar nuestros repositorios dentro de tableros virtuales.
Los tableros de proyectos en GitHub nos ayudan a organizar y priorizar el trabajo. Podemos crear tableros para asignar tareas específicas, crear hojas de ruta o cronogramas, podemos hacer listas y en general llevar el seguimiento de nuestro proyecto. Con los tableros tenemos la flexibilidad de crear cualquier flujo de trabajo que se adapte a nuestras necesidades.
Si alguna vez han usado Trello o una herramienta similar, es prácticamente lo mismo pero dentro de GitHub.
Veamos de qué se trata, daremos clic en crear un nuevo tablero, lo primero que nos pedirá será el nombre y opcionalmente una descripción, es este caso haremos uno para el seguimiento de tareas. Podemos escoger de varias plantillas que tiene GitHub o empezar desde cero, seleccioné la de Kanban básico y le daré en crear proyecto. Un tablero kanban es básicamente una estructura en usualmente tenemos 3 columnas las tareas por hacer, las tareas en progreso y las tareas realizadas. Podemos crear y mover las tarjetas entre estas 3 columnas simplemente arrastrándolas. E incluso la podemos convertir directamente en un Issue desde aquí o agregar uno existente, para poder tener un mejor control de las cosas que están pasando en nuestro proyecto.
Podemos crear cuantos tableros queramos y nos va mostrando una barra con el avance de cada tarjeta dependiendo de la columna en la que se encuentre.
Otra parte importante para tener organizados nuestros repositorio es la documentación. Una buena documentación es clave para el éxito de cualquier proyecto. Hacer que la documentación sea accesible permite a las personas una mejor colaboración dentro del proyecto; y facilita el entendimiento a otros usuarios que quieran utilizar nuestro trabajo. Para esto veremos 3 elementos:
README
El primero de ellos, del cual ya hablamos un poco es el archivo README. Estos son una forma rápida y sencilla para que otros usuarios aprendan más sobre nuestro trabajo y es una buena idea tener al menos uno en nuestro proyecto, porque es lo primero que muchas personas leerán cuando encuentren a nuestro repositorio por primera vez.
Los README generalmente siguen un formato para orientar inmediatamente a los usuarios en los aspectos más importantes del proyecto y suelen contener la siguiente información:
- Nombre del proyecto: el nombre de su proyecto es lo primero que la gente verá al desplazarse hacia abajo a su archivo.
- Descripción: Lo siguiente es incluir una buena descripción clara y breve.
- Tabla de contenido: opcionalmente, podemos poner una tabla de contenidos para permitir que otras personas naveguen más rápidamente por READMEs.
- Instalación: En caso de que nuestro repositorio sea un software que requiera de instalación, podemos detallar el proceso para ejecutar los archivos desde la máquina local.
- Uso: la siguiente sección es el uso, en el que se instruye a otras personas sobre cómo usar su proyecto después de que lo hayan instalado. Este también sería un buen lugar para incluir capturas de pantalla.
- Contribución: los proyectos más grandes a menudo tienen secciones sobre cómo contribuir al proyecto, en las que se describen las instrucciones de contribución.
- Créditos: incluir una sección de créditos para resaltar y vincular a los autores de su proyecto.
- Licencia: Finalmente, es útil incluir una licencia de nuestro proyecto. Esto nos permitirá definir con qué fin podrán otras personas utilizar nuestro trabajo, si quieres saber más al respecto puedes consultar este link: https://choosealicense.com/
Pero los README deben contener sólo la información necesaria para que los usuarios comiencen a usar y contribuir a nuestro proyecto. Una documentación más larga es más adecuada para wikis, que será lo que veremos a continuación.
Wikis
Los wikis nos ayudan a presentar información detallada sobre nuestro proyecto de una manera útil. Cada repositorio en GitHub viene con una wiki. Podemos configurar la desde la sección de Wiki y empezar a agregar páginas.
El contenido de la wiki está diseñado para ser fácilmente editable. Podemos agregar o cambiar contenido en cualquier página wiki haciendo clic en el botón Editar ubicado en la esquina superior derecha de cada página.
Y por último veremos el aspecto social de GitHub, con más y más personas usando GitHub y agregando proyectos todos los días, mantenernos al tanto con todos ellos puede ser difícil. Sin embargo, esto puede ser fácil gracias a las funciones como:
Seguir usuarios o repositorios. Cuando sigues a alguien, podrás ver su actividad en la página de inicio de GitHub.
Podemos también destacar repositorios para guardarlos en nuestros favoritos.
La página Explorar tiene repositorios que han sido destacados por personas a las que sigues, personal de GitHub y repositorios de tendencias generales directamente en la primera página. Si desea recibirlos como un boletín diario, semanal o mensual, consulte el anuncio del boletín en la parte inferior de la página Explorar.
¿Cómo darle formato al texto usando el lenguaje Markdown?, ¿qué diferencia existe entre estos archivos y el texto normal?, así como un par de cosas especiales que nos permite hacer GitHub usándolo.
Para empezar ¿qué es Markdown? Es una sintaxis ligera y fácil de usar para darle formato al texto, insertar imágenes, bloques de código y más. Este lenguaje sirve para diseñar y publicar contenido en la web, crear documentos y más. Pero principalmente, es solo texto normal con algunos caracteres como hashtags o asteriscos y una extensión de archivo .md.
Esta sintaxis sirve también en prácticamente cualquier lugar en GitHub en donde podamos escribir un comentario, por ejemplos en los Issues, Pull Requests, Wikis, etc.
Ahora veremos una descripción general de la sintaxis de Markdown.
Los encabezados simplemente se escriben anteponiendo un hashtag, y podemos agregar más hashtags dependiendo del nivel de encabezado que queramos, usualmente GitHub interpreta hasta 6 niveles aunque esto puede variar.
# This is an <h1> tag
## This is an <h2> tag
###### This is an <h6> tag
Para hacer énfasis en alguna palabra o conjunto de palabras, tenemos varias opciones:
- Podemos usar asteriscos o guión bajo para cursivas.
- Doble asteriscos o guión bajo para negritas.
- Y también podemos combinarlos.
*This text will be italic*
_This will also be italic_
**This text will be bold**
__This will also be bold__
_You **can** combine them_
Podemos agregar y dar formato también a:
- Listas
- Enlaces
- Imágenes
- Citas
- Código
GitHub.com utiliza su propia versión de la sintaxis de Markdown que proporciona un conjunto adicional de funciones útiles, muchas de las cuales facilitan el trabajo con el contenido de GitHub.com. Por ejemplo las menciones usando arroba o las referencias a Issues.
¡GitHub admite emoji! Para ver una lista de todas las imágenes que admitimos, consulte la Hoja de trucos de Emoji.