Saltar al contenido

Contribución a los proyectos

Si te tropezaste aquí preguntándote, ¿qué diablos es GitHub? Empecemos con el hecho de que es el mayor punto o centro de código abierto y desarrollo mundial. Utiliza un sistema de versionado de código fuente llamado Git, que es muy poderoso y se presta bien a las comunidades de código abierto.

En GitHub encontrarás todo tipo de gemas ocultas que pueden ayudarte a ser un mejor desarrollador. Paso al menos unos minutos cada día navegando y buscando nuevos proyectos, inspeccionando el código y aprendiendo de la comunidad. En resumen, GitHub es, con diferencia, la forma más fácil de gestionar tu código fuente, proyecto y documentación. Por lo tanto, vamos a echar un vistazo a algunos fundamentos de GitHub y cómo empezar.

Inscripción

Para empezar este tutorial de GitHub para principiantes, primero regístrate en la página web. Asegúrate de elegir bien tu nombre de usuario, y trata de no utilizar ningún carácter especial como guiones o guiones bajos; la legibilidad es clave. Este nombre de usuario se utilizará en los enlaces y la navegación de todos sus proyectos en el futuro.

Su perfil

Como cualquier perfil online, esta sección contiene mucha información sobre ti, tu actividad y los proyectos en los que trabajas. Aquí hay un ejemplo mío:

Hay tres partes principales en su perfil que incluyen información personal, información de depósito e información de contribución. Tu información personal es tu avatar, información de contacto, seguidores, estrellas y organizaciones, mientras que la información del repositorio de Git contiene una lista de todos los repositorios con los que has interactuado. Estos se dividen en dos categorías tituladas “Personal” y “Contribuido a”. Los repositorios personales son todos los proyectos y el código fuente que has configurado en tu perfil. Si haces algo con el repositorio de proyectos de otra organización (repo), aparecerá en la sección “Contribuido a”.

Las contribuciones se consideran a menudo como el indicador de la actividad en GitHub. Debajo de la sección de su repositorio hay un gráfico en blanco. Cada cuadrado se vuelve de color verde oscuro con más contribuciones para ese día (aquí hay un ejemplo de un gráfico de contribución activa). Si tus contribuciones no aparecen cuando pulsas commits, deberías asegurarte de que tu correo electrónico está configurado en tu configuración de git en tu máquina de desarrollo. Si no coincide con el correo electrónico en tu perfil GitHub, no recibirás crédito por ello.

Debajo de esa sección hay una lista de contribuciones. Haciendo clic en uno de los bloques verdes de tu perfil (o del perfil de otra persona) puedes filtrar y ordenar las contribuciones de ese día. Esto te permite ir a una contribución específica para inspeccionarla, comentarla o modificarla.

Encontrar proyectos

Hay muchas razones para buscar proyectos en Github, y es extremadamente fácil hacerlo. Puedes buscar para encontrar una herramienta/código para usar en tu proyecto personal o de equipo, encontrar un nuevo proyecto al que contribuir o encontrar un proyecto experimentado y maduro del que aprender conceptos. Para empezar, busca la barra de búsqueda en la parte superior de la pantalla. Tiene dos modos: Global y Repositorio.

Cuando estás en global puedes buscar por cualquier cosa (cue Google). Busquemos en JavaScript. Lo primero que aparecerá son repo$0027s con el nombre Javascript en ellos. Esto no nos ayuda mucho, porque estamos buscando algo genial que tenga Javascript. Pero es un buen punto de parada para cubrir las secciones de la pantalla de búsqueda.

Esto también tiene varias secciones como el perfil. A la izquierda tienes tres secciones inmediatas. Dos de ellas ayudan a refinar tu búsqueda, y una te da más información. La primera que se muestra en nuestro ejemplo es el tipo de búsqueda. Puedes usarlo para decirle al motor de búsqueda si estás buscando repositorios, texto en código, texto en temas o un usuario. En este caso estamos buscando un repositorio, así que lo dejaremos donde está.

La siguiente sección es un selector de idioma. Esto te ayuda a clasificar sólo los proyectos que contienen los siguientes idiomas. Desde que buscamos en JavaScript, está obviamente en la parte superior con 82.000 repositorios. Me adelantaré y lo seleccionaré para refinar un poco nuestra búsqueda.

Finalmente, a la izquierda está la búsqueda avanzada. Puedes jugar con eso más tarde si quieres, pero quería señalar la hoja de trucos. Puede ser muy útil para refinar tu búsqueda. Veo que hay una trampa para mostrar los depósitos con una cierta cantidad de estrellas. Seguiré adelante y perfeccionaré mi búsqueda para tener sólo repositorios con más de 1000 estrellas.

Aquí están los nuevos resultados de la búsqueda:

Como pueden ver, la nueva búsqueda es mucho más refinada. Pasamos de unos 130.000 depósitos a sólo 497. Hay muchos tipos diferentes, pero ya que estoy buscando un proyecto activo voy a ordenar por Recién Actualizado. Echa un vistazo al resultado final a continuación, ya que esto es lo que elegiremos para la siguiente sección de este post.

La página del proyecto

Ahora que hemos hablado de la función de búsqueda para encontrar proyectos en GitHub, hablemos de la página del repositorio. En primer lugar, GitHub ha puesto mucho trabajo en la interfaz de usuario y la experiencia de usuario de esta página. Cubriremos las partes principales de la página principal del repositorio, junto con algunos de los enlaces. Y luego entraremos en el uso real de esta página cuando discutamos la gestión de su proyecto.

Hay cuatro partes principales de la página del Proyecto GitHub. La parte superior (con enlaces y menús), el área de información del proyecto, el área de código fuente y, por último, el README.md en la parte inferior. En el encabezado, encontrarás enlaces a Código, Ediciones, Solicitudes de tirada, Pulso y Gráficos. Cada uno de ellos tiene su propio propósito:

  • Código: El código fuente real del proyecto
  • Problemas: Características: Sugerencias, errores, mejoras y conversaciones sobre el proyecto.
  • Tire de las solicitudes: Código que se ha presentado para formar parte del proyecto.
  • Pulso: Análisis y visión general de la actividad del proyecto.
  • Gráficos: Análisis más profundos e información sobre todo tipo de detalles del proyecto.

También encontrarás tres botones conocidos como Reloj, Estrella y Tenedor. Tómese un tiempo para familiarizarse con estos:

  • Observa: Esto le permite recibir notificaciones de toda la actividad en un repo. Ten cuidado al observar los repositorios altamente activos o recibirás una bandeja de entrada de correo electrónico llena de mensajes.
  • Estrella: Esto es como el amor, el favorito de GitHub. Marcando esto marcará este repositorio bajo tu área de Estrellas en tu Perfil Personal; recuerda eso bajo tu avatar.
  • Creo que este es el botón más importante de la página. Fork es un concepto de Git y de contribución de código fuente. Si vas a contribuir a un proyecto, tendrás que bifurcarlo y hacer tus ediciones en tu propia versión del código. GitHub hace esto fácil al hacerlo por ti cuando presionas este botón.

Debajo de estos tres importantes botones, verás el área de información del proyecto. Esta área muestra el número de compromisos, ramas, liberaciones y contribuyentes en el proyecto.

  • Se compromete: Estas son las bases del sistema de versiones de Git. En lugar de empujar todo el código al servidor cada vez que haces cambios, el sistema sólo almacena lo que son esos cambios. Esto hace que sea fácil retroceder y ver lo que alguien ha hecho realmente con el código. Una confirmación es un paquete de todos los cambios realizados desde la última confirmación.
  • Ramas: Cuando se trabaja en una idea específica, hay que dejar en paz el código principal. Aquí puedes copiar tu código a una nueva “Rama” y allí puedes hacer tus cambios sin modificar el original. Cuando sientas que tienes un buen código, lo hayas probado y quieras moverlo de nuevo a la rama principal, puedes hacerlo con una petición de extracción. (Más sobre eso en las próximas secciones.)
  • Liberaciones: Este es un lanzamiento de versión; hazle saber a GitHub que marque este compromiso como paquete completo. La gente puede ir aquí y descargar el código como estaba en cada lanzamiento.
  • Contribuyentes: Los colaboradores son personas que han trabajado y ayudado a mantener un proyecto.

Haciendo clic en la parte coloreada debajo de esa barra se revelarán las estadísticas de la distribución de los lenguajes de programación utilizados en el programa.

La siguiente sección le permite atravesar el código del proyecto. Pero ten en cuenta que si editas la nota de código de otra persona, se bifurcará a tu propio repositorio para su edición. Si hicieras clic en un archivo, te llevaría al editor de archivos. Por ejemplo, si hago clic en AUTORS.es.txt, muestra quién ha enviado la última confirmación, una línea de colaboradores, cuántas líneas de código, el tamaño del archivo y más:

Fíjese en los botones de la parte superior derecha del editor:

  • Raw: Esto abrirá una nueva ventana y mostrará el contenido en bruto del archivo. Permitiéndole seleccionarlo todo para copiarlo.
  • Culpa: Esta es otra vista del código. Muestra todas las confirmaciones recientes a la izquierda con el código a la derecha, para cada línea del código.
  • La historia: Esto muestra en orden cronológico los cambios realizados en este archivo.
  • Abrir en el escritorio de GH: Esto descargará el archivo y lo abrirá en el software de control de fuentes de escritorio de GitHub.
  • Editar: Si este es tu archivo, lo abrirá para que lo edites y lo actualices. Si es el archivo de otra persona, lo abrirá en un tenedor para que lo edites.
  • Borrar: De nuevo, si este es tu archivo, sólo borrará el archivo. Si es el archivo de otra persona, bifurcará el proyecto a tu propio repositorio y borrará este archivo de él.

De vuelta en la página principal de repo, puedes ver la sección debajo de los archivos que se llama el LÉAME. Este es el principal punto de documentación de todos los repositorios de GitHub. Lo usas para describir tu proyecto y más.

Creación de un proyecto

Es fácil crear un proyecto, sólo tienes que hacer clic en el signo más en la parte superior de cualquier página y elegir Nuevo depósito.

En la siguiente página, rellene los detalles. Haga clic en “inicializar este repositorio con un LÉAME” (la mayoría de las veces elijo la licencia del MIT). Si haces clic en el signo de información al lado de la licencia, GitHub puede decirte todo sobre los diferentes tipos de licencias disponibles. (Nota: Debido a los términos de servicio de GitHub, debes usar una licencia de código abierto para los repositorios públicos). Después de rellenarlo, puedes hacer clic en “Crear un repositorio”. Aquí está mi repositorio para este post:

Gestión de un proyecto

Una vez que crees un repositorio Git, tendrás que administrarlo. Hay muchas cosas que van con la gestión de un repositorio GitHub, pero te prometo que no es nada que no puedas manejar. Vamos a recorrerlo juntos.

Léeme

Primero, establece un README.md. Este se encuentra en el directorio raíz de su proyecto y puede ser fácilmente editado en el navegador. El readme utiliza la sintaxis de Markdown (aprende más sobre eso aquí). El Léame debe tener información básica sobre tu proyecto. Cómo descargarlo y usarlo, así como otras pequeñas tareas a realizar. Mira este sólido ejemplo de un Léame.

Para este léeme, sólo describiremos el depósito. Aquí está mi nota para ello:

The-Definitive-Guide-To-Github

Este es el repo usado en un artículo publicado en Pluralsight. Estoy haciendo este repositorio para permitir que otros lo vean después de leer el artículo. También me permite hacer capturas de pantalla y realizar acciones junto con la escritura del post… esta es una buena práctica para asegurarme de que no me pierdo nada.

Puedes encontrar el artículo en [Este enlace](http://insertarticlelinkehere)

Puedes hacer mucho mientras editas este archivo, incluyendo la vista previa de los cambios y el cambio de nombre. Cuando termines de editar necesitas nombrar tu confirmación (recuerda, estás empujando los cambios, así que esto será empaquetado como una confirmación y puesto en tu repositorio) y una descripción de lo que has cambiado. Puedes ver lo que he hecho aquí:

Cuando guarde eso, tendré una página readme actualizada en el repositorio:

Ediciones

Los temas son probablemente la segunda parte más importante de GitHub. Los problemas hacen que cosas como la gestión de errores y las solicitudes de características sean pan comido. Primero debes saber que los temas abiertos son verdes y los cerrados son rojos. Para crear un nuevo número sólo tienes que pulsar el gran botón verde de “Nuevo número”. Ponle un título a tu número y luego descríbelo. Puede ser cualquier cosa, desde un error, una mejora, una petición de ayuda, o incluso sólo una pregunta. Estas descripciones se conocen como Etiquetas; las etiquetas se pueden seleccionar a la derecha. También puedes seleccionar un hito si has creado uno, o asignar a alguien. (Ten en cuenta que algunas de estas acciones requieren que seas propietario de un repositorio). Una vez que hayas terminado, haz clic en “Enviar nuevo número”.

Puede ver los detalles sobre un tema directamente desde la página del tema, incluyendo todos los campos que acabamos de rellenar al enviar el tema. Puedes enlazar los números entre sí usando #issuenumber y enlazarlos con las confirmaciones usando el “hash de confirmación”. Aquí es donde tendrás la discusión de tu tema para futuras conversaciones, hasta que se cierre.

Aquí hay un ejemplo de un tablero de temas activos:

Hitos

Puedes acceder a los hitos dentro del área de temas. Puedes usarlos para segmentar y planificar tu proyecto. Sólo tienes que establecer un nombre y una fecha de vencimiento, y luego las ediciones pueden ser asignadas a los hitos, lo que te permite almacenar y gestionar las ediciones fácilmente.

Wiki vs. Páginas GitHub

Las páginas Wiki sirven como un área separada para almacenar su documentación en formato de reducción. Esto separa su código de su documentación; sin embargo, dependiendo de sus preferencias personales, esto podría ser bueno o malo. Cabe señalar que la mayoría de los nuevos proyectos utilizan las páginas GitHub para la documentación porque esto permite el uso de generadores de documentación como Mr-Doc para generar las páginas html a partir de los comentarios en su código fuente. Mientras que el wiki puede ser una forma rápida de iniciar la documentación, recomiendo el uso de GitHub Pages.

GitHub Pages es una de las nuevas adiciones a la plataforma GitHub. Te permite alojar sitios web estáticos de forma gratuita (esto me ha llevado a abandonar todo mi alojamiento de pago y a trasladar todo a las páginas de GitHub). El sistema utiliza un software llamado Jekyll para generar y mantener los archivos estáticos, y es fácil de usar. Puedes aprender sobre Jekyll aquí, pero mientras tanto, piensa en él como WordPress para la línea de comandos.

Para usar GitHub Pages todo lo que tienes que hacer es crear una nueva rama en tu repositorio llamada “gh-pages”. Coloca tus archivos web estáticos (html, css, js, imágenes) en la rama y se servirá sobre una URL como http://your-username.github.io/repository-name. ¡Es tan simple como eso! Oh, y como bonus, GitHub te permite usar tu propio nombre de dominio gratis; usa eso para alojar tu sitio completo en un nombre de dominio de tu elección.

Construyendo una comunidad

Supongo que más de la mitad de los repositorios de GitHub son proyectos de código abierto. Los proyectos de código abierto tienden a funcionar bien para las comunidades, y debido a esto querrás proporcionar formas para que tu comunidad crezca. Veamos algunas formas diferentes de hacerlo.

Integrar con Slack

La holgura es una gran herramienta de comunicación, y quizás una de las más calientes en este momento. Es gratis de usar y configurar, y con algunas API bien programadas puede convertirse en una gran comunidad. Prefiero Slack porque puede ser usado para múltiples proyectos, tiene una aplicación móvil, y es simple de usar. También puedes integrar Slack con GitHub usando un servicio llamado, “If This Then That”. IFTTT te permite construir disparadores. Tengo muchas configuraciones para el Slack de mi equipo (como cuando se publica un nuevo número en cualquiera de mis repositorios de GitHub, éste notifica automáticamente a la gente a través de Slack).

Integrar con Trello

Trello es una buena herramienta para mantener su proyecto organizado. Puedes usarlo para organizar las tarjetas en categorías. Esto podría ser una nueva característica en la categoría En progreso. He usado un flujo IFTTT para publicar nuevos temas en un Tablero Trello donde luego puedo trabajarlos y moverlos a través de mi flujo de trabajo de gestión de tareas.

Integrarse con Gitter

Gitter es una alternativa a Slack. No lo he usado mucho, aunque muchos depósitos lo hacen. Una cosa a tener en cuenta es que si trabajas detrás de un firewall corporativo, pueden bloquear los nombres de dominio “.im”.

Esta puede ser la parte más fuerte de GitHub. Para el resto de este post, veremos las contribuciones y cómo usar Git.

Tenedor

Antes de empezar a ayudar en un proyecto, deberías comprobar con el propietario del depósito las cosas que hay que hacer. Claro, puedes añadir tus ideas a la mezcla, pero si hay cosas importantes que necesitan ser trabajadas, es mejor empezar por ahí. Después de que decidas contribuir y tengas una idea de lo que quieres hacer, querrás bifurcar el repositorio; esto copiará el repositorio a tu propio repositorio personal. Aquí puedes clonar el repositorio (más sobre eso abajo), hacer tus cambios, y devolverlos a tu repositorio. Puedes hacer esto todo el tiempo que quieras, pero ten en cuenta que el repositorio del que te has bifurcado seguirá cambiando. Asegúrate de que mantienes tu código sincronizado con los cambios que están ocurriendo con el repositorio principal.

Petición de tirar

Una vez que haya terminado de hacer cambios en su depósito, los haya probado, y esté seguro de que están listos, tendrá que presentar una solicitud de extracción. Me adelantaré y haré un pequeño cambio en el Tutorial de Pluralsight y enviaré una solicitud de extracción para que puedas ver cómo se ve. Puedes ver abajo que cuando hice clic para editar un artículo en el repositorio, GitHub lo bifurcó para mí. Ahora, cuando lo guarde, estaré listo para enviar una solicitud de extracción.

Basándome en mis preferencias personales, revisaré y actualizaré los bloques de código de este archivo para que tengan resaltado la sintaxis. Después de que termine de editar, agregaré un título y una descripción y haré clic en “proponer cambio de archivo”.

Después de hacer clic en eso, veré una página de comparación de cambios donde puedo ver que cambié un archivo y añadí 15 nuevas líneas de código. También puedes ver que voy a presentar una solicitud de fusión (pull request) desde mi horquilla principal de “shadowcodex/tutoriales” a la horquilla base de “pluralsight/tutoriales”. A continuación, voy a pulsar el botón verde “Crear solicitud de extracción” y la presentaré.

A continuación, se me pedirá que titule y comente mi solicitud de extracción. GitHub tuvo la amabilidad de rellenar esto desde el área de cambios de mi archivo de propuestas. Voy a seguir adelante y decir que es lo suficientemente bueno y hacer clic en el botón verde “Crear solicitud de extracción” para terminar la presentación.

Así es como se ve el final de mi contribución:

Git Basics: Introducción a Git

Como se mencionó brevemente antes, Git es un sistema de control de código fuente. Ha sido diseñado para funcionar para todo, desde proyectos de pequeña a gran escala. Es fácil y eficiente. Para obtener una comprensión completa de Git puedes dirigirte aquí. Para descomponerlo, el concepto que seguirás alrededor del 90 por ciento del tiempo es este:

  1. Clon
  2. Hacer cambios
  3. Comprometerse
  4. Push Commit to Server

o

  1. Tenedor
  2. Clon
  3. Hacer cambios
  4. Comprometerse
  5. Push Commit to Server
  6. Presentar la solicitud de extracción

Clonación

Cuando crees tu proyecto en GitHub, verás en su página principal un enlace que se parece a esto:

Una vez que hayas instalado Git, todo lo que tienes que hacer para que este código llegue a tu máquina es ejecutar el siguiente comando usando ese enlace.

Shell

$ git clon https://your-github-link

Esto copiará toda la rama maestra (o su rama por defecto) a su máquina local.

Comprometerse

Una vez que hayas clonado tu repositorio, eres libre de hacer cambios en los archivos. Cuando hayas terminado, querrás devolver los cambios a GitHub. Para ello vamos a hacer una confirmación que almacenará todos los cambios en un paquete listo para ser enviado al servidor. Los siguientes comandos añadirán todos los cambios a una confirmación para ti. (Asegúrate de estar en el directorio raíz de tu proyecto antes de ejecutar estos comandos).

El primer comando añade todos los archivos a su escenario y se prepara para confirmarlos:

Si ha borrado archivos, puede que obtenga un error al ejecutar este comando. Está bien, sólo ejecuta el siguiente comando en su lugar:

Ahora estás listo para hacer tu compromiso usando este comando:

Shell

$ git commit -m $0027introduce tu mensaje de confirmación aquí describiendo lo que hiciste$0027

¡Tu compromiso debería estar listo ahora! Puedes tener tantos compromisos como quieras en tu máquina local (yo me comprometo cuando termino las partes principales del proyecto). Una vez que haces un push, se enviarán todas las confirmaciones que no estén sincronizadas con el servidor.

Empuje

Ahora que tienes tu confirmación lista, querrás empujarla al servidor, lo cual es fácil de hacer con este comando:

Te pedirá tu nombre de usuario y contraseña. Una vez que los haya introducido correctamente, enviará todas las confirmaciones al servidor, ¡y listo!

Tira

Si haces cambios en el repositorio remoto, querrás llevar esos cambios a tu repositorio local (suponiendo que ya lo hayas clonado). Puede hacer esto con el comando pull:

Pago

Si has creado una rama con la que trabajar en GitHub, puedes cambiar fácilmente a esa rama en tu máquina local ejecutando el siguiente comando:

Tshell

$ git checkout your-branch-name

Además, recomiendo que los principiantes de Git y GitHub hagan todas las solicitudes de tirada en el sitio web; esto lo hace más fácil.

Takeaway

Bien, eso fue una tonelada de información a la vez, pero antes de que empieces a sentirte abrumado, recuerda que aprender GitHub, al igual que aprender cualquier cosa nueva, lleva tiempo. Usa esta guía como un mapa mientras navegas por GitHub y estarás en camino de dominarlo mucho más rápido de lo que podrías haber imaginado. Una vez que sientas que has empezado a saber cómo usar GitHub y que ya lo tienes todo controlado, asegúrate de consultar más tutoriales de Pluralsight y de llevar tus habilidades al siguiente nivel.