Introducción

Esta guía contiene la documentación para iniciarse en el Open Source. Aprenderás sobre:

Únete a nuestro canal de discusión y entérate de lo que esta pasando:

• https://github.com/GDGJaen/charlas/discussions/3

Slides de la charla:

• Introducción
• ¿Qué es el Open Source?
• ¿Cómo contribuir?
  • ¿Qué significa contribuir?
  • Encuentra tu comunidad
• Introducción a Git
• Pull Request
  • Paso 1. Fork
  • Paso 2. Crea una rama
  • Paso 3. Mantén tu fork actualizado
  • Paso 4. Crea un commit
  • Paso 5. Push
  • Paso 6. Crea un pull request
• Lanza tu propio proyecto

Contribuidores

¿Qué es el Open Source?

El código abierto es un término que originalmente se refería al software de código abierto (OSS). El software de código abierto es un código diseñado para ser de acceso público: cualquiera puede ver, modificar y distribuir el código como mejor le parezca.

El software de código abierto se desarrolla de forma descentralizada y colaborativa. El software de código abierto es a menudo más barato, más flexible y tiene más longevidad porque es desarrollado por comunidades en lugar de un solo autor o empresa¹.

¿Cómo contribuir?

¿Quieres colaborar en un proyecto Open Source? Da con nosotros los primeros pasos en esta guía resumida, inspirada por Open Source Guides.

Contribuir a proyecto de otras personas puede incluso abrirte las puertas a tu próximo trabajo. Porque al final del día no solo estás aportando código, también estás expandiendo tu red de contactos al interactuar con otros contribuidores.

¡Literalmente estarás a los ojos de todo el mundo con tus aportaciones!

¿Qué significa contribuir?

No necesitas contribuir solo con código.

Otras maneras de involucrarse con un proyecto

Contribuye de acuerdo a tus gustos.

• ¿Te gusta planificar eventos?

  Ayuda organizando conferencias alrededor del proyecto.

• ¿Te gusta diseñar?

  Mejora la usabilidad del proyecto, reúne una guía de estilos para ayudar a tener una consistencia visual, etc.

• ¿Te gusta escribir?

  Escribe y mejora la documentación del proyecto, muestra cómo se puede usar el proyecto, etc.

• ¿Te gusta organizar?

  Vincula los problemas relacionados y sugiere etiquetas para los problemas.

• ¿Te gusta programar?

  Pregunta si puedes ayudar con algo, encuentra un problema abierto, etc.

• ¿Te gusta ayudar a otros a programar?

  Revisa el código que presentan otras personas ¹.

Encuentra tu comunidad

Google Summer of Code

Google Summer of Code es un programa global centrado en atraer a más estudiantes al desarrollo de software Open Source. Los estudiantes trabajan con una organización de código abierto en un proyecto de programación de 10 semanas durante sus vacaciones universitarias ¹.

¡Prepárate con tiempo conociendo el programa de años anteriores! ²:

Únete al grupo de discusión de Google Summer of Code.

Guía para estudiantes

Guía para estudiantes. Si deseas aumentar tus posibilidades de ser aceptado (y tener éxito durante) Google Summer of Code, le recomendamos encarecidamente que lea esta guía. Es particularmente útil para obtener consejos sobre cómo escribir una buena propuesta de proyecto y cómo los estudiantes deben interactuar con las comunidades con las que están interesados en trabajar durante el verano.

Hacktoberfest

Hacktoberfest fomenta la participación en el Open Source, animando a los participantes a completar un desafío y regalándoles una camiseta de edición limitada³.

¿Cómo funciona?

1. Los propietarios de los proyectos Open Source participan añadiendo el tag hacktoberfest a sus repositorios.

   

2. Realizando un pull requests de calidad a través de GitHub o GitLab. En la siguiente sección explicaremos esto de pull request.

   Ejemplos de pull requests de baja calidad:

   1. Pull requests automáticos. Ej. Eliminar espacios en blanco / corregir errores tipográficos / optimizar imágenes.
   2. Pull requests que son considerados por el responsable del proyecto como un obstáculo frente a una ayuda.
   3. Algo que claramente es un intento de simplemente hacer +1 en el recuento de los pull requests.
   4. Por último, pero no menos importante, un pull request para corregir un error tipográfico está bien, pero 5 pull requests para eliminar un espacio en blanco perdido no lo están.

Buscando proyectos

Quieres participar pero no sabes por dónde empezar, no te preocupes, aquí te damos una lista de referencia por la que puedes comenzar:

• The Dev Team. Suelen anunciar el HacktoberFest todos los años, y los responsables de proyectos acuden para anunciar sus proyectos en la sección de comentarios.

• GitHub. Buscando por el topic Hacktoberfest verás ¡más 84.000 repositorios públicos en los que participar!

  • Awesome for Beginners. Una lista de proyectos increíbles para principiantes usando C, C++, Go, Java, Python, JavaScript y mucho más.

Good first issue

Con el fin de ayudar a los nuevos colaboradores a comenzar, los propietarios de muchos proyectos etiquetan algunos problemas por resolver con good first issue, para indicar que son lo suficientemente simples como para que los principiantes los aborden, aumentando de este modo las contribuciones útiles y reduciendo la fricción de los usuarios que abordan problemas que son demasiado difíciles para su nivel.

Además, viene con la ventaja añadida de... ¡tendrás un mentor guiándote durante todo el proceso!

Encuentra tu primer good first issue en:

• https://goodfirstissue.dev

Más comunidades

Investiga en la lista que han creado +500 colaboradores acerca de proyectos Open Source y que ellos mismos recomiendan:

sindresorhus/awesome: 😎 Fantástica lista sobre todo tipo de temas interesantes.

Tareas nivel intermedio

Una vez que comience a sentirse más cómodo creando pull request, puede continuar descubriendo más proyectos de código abierto que pueden necesitar tu ayuda a través de los siguientes programas:

• https://www.codetriage.com

• http://www.pullrequestroulette.com

Introducción a Git

La manera en la que Git trabaja puede ser intimidante al principio. Con una metáfora entenderemos mejor qué es eso de los pull request, repositorio local, repositorio en la nube, push, pull, etc.

Imaginemos dos estudiantes, Susana y Antonio. Susana vive en Canada y Antonio en España.

Susana hace muy buenos apuntes de matemáticas. La manera en la que ella trabaja es la siguiente:

1. Escribe las notas a mano
2. Después las escanea y los sube a la nube, donde todos puedan descargar sus apuntes

Antonio encuentra los apuntes de Susana y los descarga

Ahora tanto Susana como Antonio tiene una copia exacta de los apuntes de matemáticas.

En Git, a esto se le conoce como hacer un fork de un proyecto.

Antonio le pasa como a Susana, le gusta trabajar con apuntes en físico. Es por ello que se los imprime.

En Git, esto se le conoce como hacer un pull de nuestro repositorio en la nube a nuestro repositorio local.

Pasados unos días, Antonio descubre que había un cálculo mal hecho en los apuntes de Susana y se dispone a corregirlo en su cuaderno.

Sin embargo, Susana ha sido muy buena poniendo a disposición de todos sus apuntes. Antonio quiere agradecerle su gesto notificicándole la errata que encontró.

¡Houston, tenemos un problema! Antonio lo ha corregido en su cuaderno, pero no puede enviarle su cuaderno a Susana. Espera, ¡sí puede! de la misma forma que hizo Susana.

Antonio señala con un marcador fluorescente el error y más abajo añade la corrección.

En Git, esto se le conocerá como hacer un commit, es decir, registrar los cambios que se le han hecho al documento original. Los commits, como ya veremos, llevan asociados mensajes descriptivos.

Ahora sí, Antonio puede escanear los apuntes, subirlos a su nube y notificar a Susana de los cambios realizados.

Más adelante, Susana revisará la aportación de Antonio para:

• si Antonio no tiene razón, no actualizar sus apuntes
• si por el contrario, Antonio tiene razón, Susana corregirá sus apuntes para no sacar un cerapio

En Git, esto se le conoce como hacer un pull request, es decir, notificar al creador original de los apuntes sobre una posible mejora.

Conoce más sobre Git

Tanto si es tu primera vez trabajando con Git como si tienes experiencia, es normal acudir a la documentación para consultar algún comando.

Una lista de recursos útiles:

• Guía de Git oficial en español. El libro completo de Git, escrito por Scott Chacon y Ben Straub.
• Guía de Git por GitHub (inglés)
• Guía de Git por Make it Real
• Tutorial de Git (YouTube). Si te va el contenido audiovisual, esta es tu lista de reproducción.

Pull Request

¿Qué es un Pull Request?

Un pull request es un evento en Git donde un colaborador le pide al mantenedor de un repositorio de Git (propietario o mantenedores del repositorio) que revise el código que desea fusionar al proyecto¹.

En nuestra metáfora, Antonio pidiéndole a Susana que revise el 2+2=5.

Paso 1. Fork

El primer paso es hacer un fork del repositorio al que queremos hacer un pull request.

Un fork es una copia de un repositorio. El fork de un repositorio te permite experimentar libremente con los cambios sin afectar el proyecto original.

En nuestra metáfora, Antonio descargándose los apuntes de Susana.

La guía de GitHub es tremenda. En ella podrás ver una guía, paso a paso, de cómo hacer un fork en GitHub¹.

Es tan fácil como:

1. En GitHub, estando en el repositorio al que le queremos hacer un fork:

   

Paso 2. Crea una rama

Utilice una rama para aislar el trabajo de desarrollo sin afectar a otras ramas del repositorio. Cada repositorio tiene una rama predeterminada y puede tener varias otras ramas.

Comandos importantes1

Para ver las ramas existentes, ejecuta el comando:

git branch

Para crear una nueva rama, ejecutar el comando:

git branch NOMBRE_NUEVA_RAMA

Para moverse a una rama existente, ejecuta el comando:

git checkout NOMBRE_RAMA

Hay un atajo para crear y moverte a la nueva rama al mismo tiempo.

git checkout -b NOMBRE_NUEVA_RAMA

Git no te permitirá eliminar una rama en la que te encuentres actualmente. Primero necesitas moverte a una rama diferente, y luego ejecutar el comando:

git branch -d RAMA_A_ELIMINAR

Buenas prácticas

El GitFlow Workflow es una metodología de trabajo basada en el división de las distintas etapas de producción de software en distintas ramas del repositorio ².

• master: En la rama máster se encuentran las releases estables de nuestro software. Esta es la rama que un usuario típico se descargará para usar nuestro software, por lo que todo lo que hay en esta rama debería ser funcional. Sin embargo, puede que las últimas mejoras introducidas en el software no estén disponibles todavía en esta rama.
• develop: En esta rama surge de la última release de master. En ella se van integrando todas las nuevas características hasta la siguiente release.

Y mucho más que puedes aprender en Buenas prácticas al trabajar con Git por David Estevez.

Si te interesa saber más sobre el tema, te recomendamos leer A successful Git branching model.

Paso 3. Mantén tu fork actualizado

Estás contribuyendo a un proyecto de código abierto y notaste que tu fork no está sincronizado con el repositorio original. ¿Cómo puedes corregir eso?

Susana puede actualizar sus apuntes y el resto de personas puede descargarse los apuntes actualizados siempre que deseen.

Sincronizando un fork (por GitHub) 1

Desde la interfaz gráfica

Tan simple como hacer click en Fetch upstream:

Desde la terminal 2

¿Sabías que tu fork es huérfano? Si listas el repositorio remoto configurado, solo verás tu fork como origen:

git remote -v

output:

origin  https://github.com/YOUR_USERNAME/YOUR_FORK.git (fetch)
origin  https://github.com/YOUR_USERNAME/YOUR_FORK.git (push)

Necesitamos configurar esta información para restaurar la relación familiar con el repositorio original al que le hicimos un fork:

1. Agregar un nuevo repositorio remoto conectado al proyecto del propietario

   
   
   Procesos que intervienen al sincronizar un fork

   git remote add upstream https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git
   

2. ¡Salvaste a la familia! Ahora puedes ver el repositorio original y tu fork:

   git remote -v
   

   output:

   origin    https://github.com/YOUR_USERNAME/YOUR_FORK.git (fetch)
   origin    https://github.com/YOUR_USERNAME/YOUR_FORK.git (push)
   upstream  https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git (fetch)
   upstream  https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git (push)
   

3. Sincronizada tu fork.

   1. Asegúrate que estás en la rama master de tu proyecto.

      git checkout master
      

   2. Ahora, puedes traer los cambios del repositorio original a tu fork.

      git fetch upstream
      

      output:

      remote: Enumerating objects: 16, done.
      remote: Counting objects: 100% (16/16), done.
      remote: Compressing objects: 100% (7/7), done.
      remote: Total 7 (delta 5), reused 0 (delta 0), pack-reused 0
      Unpacking objects: 100% (7/7), 1.72 Kio | 160.00 Kio/s, done.
      From https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY
         909ef5a..0b228a8  master     -> upstream/master
      

Paso 4. Crea un commit

Ya has creado esa magnífica feature. Toca registrarla en el historial de Git, realizando un commit.

Los commits están en el corazón del uso de Git. Puedes pensar en un commit como una captura de tu proyecto, donde se crea una nueva versión de ese proyecto en el repositorio actual. Dos características importantes de los commits son:

• puedes recordar los cambios a los que se les hizo commits en una fecha posterior, o revertir el proyecto a esa versión
• si varios commits editan diferentes partes del proyecto, no se sobrescribirán entre sí aunque los autores de los commits no se conozcan entre sí. Este es uno de los beneficios de usar Git sobre una herramienta como Dropbox o Google Drive ¹

¿Recuerdas cuando Antonio marcó con un marcador fluorescente los cambios que hizo a los apuntes de Susana y añadió un mensaje?

Pasos a seguir

El ciclo de vida del estado de tus archivos

1. Antes de realizar el commit, indica a Git que quieres incluir actualizaciones en un archivo (o varios). Lo que se conoce como agregar el archivo a staging.

   git add ARCHIVO1 ARCHIVO2
   

   Si quieres pasar a staging todos los archivos que han sido modificados:

   git add . 
   

2. Crea el commit.

   git commit -m "Mi mensaje"
   

   output:

   [master 13vc6b2] Mi mensaje
    1 file changed, 1 insertion(+)
   

   La opción más utilizada con git commit es la opción -m. La -m significa mensaje. Cuando se llama a git commit, es necesario incluir un mensaje. El mensaje debe ser una breve descripción de los cambios que se han hecho. El mensaje debe estar al final del comando y debe estar envuelto entre comilla " ".

Paso 5. Push

Tenemos nuestro commit, toca subir los commits desde tu rama local en tu repositorio Git local al repositorio remoto.

Antonio escaneando los apuntes para subirlos a su nube.

Basta con el siguiente comando:

git push REPOSITORY_NAME BRANCH-NAME

Donde REPOSITORY_NAME puedes encontrarlo con:

git remote -v
origin    https://github.com/YOUR_USERNAME/YOUR_FORK.git (fetch)
origin    https://github.com/YOUR_USERNAME/YOUR_FORK.git (push)
upstream  https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git (fetch)
upstream  https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git (push)

En este caso,origin es el nombre de nuestro fork, ya que es el que está asocidado a nuestro fork:

¿Quieres más?

La guía de GitHub acerca push es lo que buscas.

Paso 6. Crea un pull request

Creando un pull request (por GitHub)1

Desde la interfaz gráfica

1. Ve a tu repositorio en GitHub y verás un botón llamado Pull request.

   

2. Escribe un título y una descripción para tu pull request.

   
3. 
   
   
   El ciclo de vida del estado de tus archivos

Desde la terminal

Es más eficiente y rápido hacerlo con GitHub CLI.

GitHub CLI es una herramienta de línea de comandos con la que puedes hacer pull requests, crear issues y otras características de GitHub, para que puedas hacer todo en un solo lugar².

Instalando GitHub CLI

1. Instala GitHub CLI.

2. Autentícate.

   gh auth login
   

Pasos a seguir para hacer un pull request

1. Ubícate en la rama sobre la que quieres hacer el pull request.

   git checkout NOMBRE_DE_LA_RAMA
   

2. Crea el pull request.

   gh pr create
   

   Sigue los pasos que te indican desde la terminal.

   Este comando admite flags, para más información consulta la documentación de GitHub CLI.

Lanza tu propio proyecto

Ahora que ya sabes cómo colaborar, probablemente estás pensando en comenzar tu propio proyecto Open Source. ¡Oleeeeeee!

Aprende más en Comenzando un proyecto de Código Abierto.

Contribuidores

Esta guía es Open Source. ¿Quieres contribuir? Empieza por el archivo CONTRIBUIR.md donde podrás informarte sobre cómo colaborar en el proyecto.

Aquí hay una lista de colaboradores que han ayudado a mejorar Primeros pasos en Open Source. ¡Únete!

Manuel

Agradecimientos

Jesi. Por la gran idea de añadir metáforas.	Abdallah. Por el feedback y las referencias de good first issue.