Contribución al código abierto

En este artículo, aprenderás a contribuir a un proyecto de código abierto mediante un ejemplo. Te guiaremos por la contribución al repositorio github/docs: te familiarizarás con el repositorio, buscarás un área para contribuir, realizarás y enviarás una solicitud de cambios y trabajarás con los mantenedores para que se acepten tus cambios.

Orientación con las instrucciones del proyecto

Antes de empezar, es importante comprender las instrucciones y los requisitos del proyecto.

¿Por qué son importantes las instrucciones?

Cada proyecto tiene sus propias convenciones, estándares de programación y procesos de contribución que deberás seguir:

• Requisitos de formato y estilo de código: cómo se debe dar formato al código, convenciones de nomenclatura y reglas de linting
• Instrucciones de pruebas: cómo ejecutar pruebas, qué pruebas son necesarias para las nuevas características y convenciones de prueba
• Proceso de solicitudes de cambios: cómo estructurar la solicitud de cambios, qué información incluir y revisar las expectativas
• Configuración de desarrollo: cómo configurar el entorno de desarrollo local, las dependencias necesarias y los procesos de compilación
• Notificación de incidencias: cómo notificar errores, solicitar características o formular preguntas
• Canales de comunicación: dónde formular preguntas, analizar cambios u obtener ayuda de los mantenedores

Dedicar tiempo a leerlas ahorrará tiempo, tanto para ti como para los mantenedores, y hará que sea más probable que se acepte tu contribución.

Búsqueda de las instrucciones

Para acceder a estas instrucciones y requisitos, ve la lista de comprobación Community Standards en la pestaña Insights. En este ejemplo, se usarán github/docs Community Standards.

• LÉAME: proporciona información general sobre el proyecto. El contenido puede variar, pero el archivo LÉAME ayuda a usuarios y colaboradores a comprender rápidamente qué es el proyecto y cómo usarlo, junto con vínculos a otra documentación.

• Código de conducta: define estándares de comportamiento aceptables para los colaboradores del proyecto y los miembros de la comunidad, y establece expectativas y procedimientos para abordar las infracciones.

• Contribución: proporciona guías e instrucciones para los colaboradores del proyecto. Ayuda a simplificar el proceso de contribución mediante el establecimiento de expectativas claras y el fomento de una colaboración coherente.

• Licencia: define legalmente cómo otros usuarios pueden utilizar, modificar y distribuir el código, lo que protege tanto a los mantenedores como a los usuarios mediante el establecimiento de términos claros para derechos de autor y permisos.

  • Por ejemplo, el repositorio github/docs usa la licencia Creative Commons para la documentación, que es un tipo de licencia específica para trabajos creativos. El código de software de github/docs se encuentra bajo la licencia MIT, que es una licencia permisiva que permite a cualquier usuario usar el código que contiene.
  • Puedes obtener información sobre otros tipos de licencias comunes con la herramienta Choose a license.

• Directiva de seguridad: proporciona instrucciones para notificar vulnerabilidades de seguridad a los mantenedores del repositorio.

Revisa cada uno de los recursos que están disponibles para el repositorio github/docs.

Búsqueda de un área para contribuir

Al contribuir por primera vez a un proyecto, empezar con correcciones menores, como mejoras en la documentación o pequeños informes de errores, puede ayudarte a familiarizarte con el flujo de trabajo de los colaboradores y el código base. En este ejemplo, buscarás incidencias en las que se usen las etiquetas help wanted y good first issue para exponer incidencias específicas que están abiertas para colaboradores externos. Después, usarás Copilot para ayudar a proporcionar contexto sobre la incidencia.

1. Ve a la pestaña Issues del repositorio github/docs, usa el filtro Labels y selecciona "help wanted" para ver las incidencias abiertas para las que los mantenedores han marcado que necesitan ayuda de la comunidad.

2. Examina la lista de incidencias y busca una en la que te interese trabajar.

3. En la parte superior derecha de cualquier página de GitHub, haz clic en el botón situado junto a la barra de búsqueda.

   Se muestra el modo de página completa, inmersiva, de Copilot Chat.

4. En el cuadro de mensaje, escribe el siguiente mensaje:

   Text

   Can you summarize the key points and next steps from this issue?
   

5. Lee el contexto que proporciona Copilot, junto con los comentarios de otros colaboradores y mantenedores para ver si la incidencia es en la que quieres trabajar. Si tienes preguntas específicas, puedes formularlas directamente en la incidencia o en Discord, IRC o Slack del proyecto, si procede.

Creación de una copia propia de un proyecto

Ya puedes comenzar a contribuir. Como no tienes acceso para editar el repositorio, primero debes crear una bifurcación: tu propia copia del repositorio, donde puedes realizar cambios de forma segura y enviarlos de nuevo para que el mantenedor los revise. En este ejemplo, te guiaremos por la creación de una bifurcación del repositorio github/docs.

1. Vaya al proyecto GitHub Docs en http://github.com/github/docs.

2. En la esquina superior derecha de la página, haga clic en Fork (Bifurcar).

3. En "Propietario", selecciona el menú desplegable y haz clic en un propietario del repositorio bifurcado.

4. De forma predeterminada, las bifurcaciones tienen el mismo nombre que sus repositorios ascendentes. Opcionalmente, para distinguir aún más la bifurcación, en el campo "Nombre del repositorio", escribe un nombre.

5. Opcionalmente, en el campo de "Descripción", escribe una descripción de la bifurcación.

6. Opcionalmente, selecciona Copiar solo la rama DEFAULT.

   En muchos escenarios de bifurcación, como los de contribución a proyectos de código abierto, solo tienes que copiar la rama predeterminada. Si no selecciona esta opción, todas las ramas se copiarán en la nueva bifurcación.

7. Haz clic en Crear bifurcación.

Clonación de una bifurcación para un proyecto

Ahora tienes una bifurcación del repositorio github/docs en tu cuenta, pero debes acceder a la máquina local para empezar a trabajar en los cambios.

1. En GitHub, navega a your fork en el repositorio github/docs.

2. Encima de la lista de archivos, haz clic en Código.

   

3. Copia la dirección URL del repositorio.

   • Para clonar el repositorio con HTTPS, en "HTTPS", haz clic en .

   • Para clonar el repositorio mediante una clave SSH, incluido un certificado emitido por la entidad de certificación SSH de la organización, haz clic en SSH y luego en .

   • Para clonar un repositorio mediante GitHub CLI, haz clic en GitHub CLI y, después, en .

     

4. En Mac o Linux, abre Terminal. En Windows, abre Git Bash.

5. Cambia el directorio de trabajo actual a la ubicación en donde quieres clonar el directorio.

6. Escriba git clone y pegue la dirección URL que ha copiado antes. Tendrá este aspecto, con su nombre de usuario de GitHub en lugar de YOUR-USERNAME:

   Shell

   git clone http://github.com/YOUR-USERNAME/docs
   

7. Presione ENTRAR. Se creará tu clon local.

Realización de cambios en una rama puntual

Ha llegado el momento de realizar cambios. Antes de empezar, se recomienda crear una rama puntual con un nombre descriptivo en la bifurcación. El uso de una rama puntual te permite mantener el trabajo independiente de la rama predeterminada del repositorio.

git checkout -b YOUR_TOPIC_BRANCH

git checkout -b YOUR_TOPIC_BRANCH

Después de cambiar a la rama puntual, abre el editor de texto o IDE que prefieras y empieza a programar. Siga estos procedimientos recomendados:

• Usa Copilot para proporcionar sugerencias de código, lo que le da confianza en los cambios.
• Documenta el código y escribe pruebas. A menudo se pasan por alto y pueden ayudar a garantizar que la contribución se fusione.
• Formula preguntas a Copilot sobre la incidencia para ayudarte a comprender mejor los requisitos de implementación.
• Usa Copilot para revisar los cambios y asegurarte de que cumplen los requisitos de documentación y estilo de programación del proyecto.
• Usa Copilot para obtener ayuda con las instrucciones para compilar y probar el proyecto en el equipo local.

Confirmar y subir tus cambios

Cuando los cambios estén listos, puedes almacenarlos provisionalmente y confirmarlos en el repositorio. Al escribir un mensaje de confirmación, usa un título de confirmación claro y conciso con menos de 50 caracteres que resuma lo que hace la confirmación. Agrupa los cambios relacionados en confirmaciones únicas cuando sea posible, pero intenta mantener los cambios no relacionados en confirmaciones independientes.

git add .
git commit -m "a short description of the change"

git add .
git commit -m "a short description of the change"

Intenta mantener las líneas de descripción de la confirmación con menos de 72 caracteres para mejorar la legibilidad. Cuando hayas terminado de confirmar los cambios locales y quieras insertarlos en GitHub, inserta los cambios en el repositorio remoto.

git push

git push

Envío de una solicitud de incorporación de cambios

Ahora que has insertado los cambios en GitHub, ya puedes abrir una solicitud de cambios. Puedes abrir una solicitud de cambios para su revisión incluso si no has finalizado los cambios realizados en la rama. La apertura de una solicitud de cambios al principio del proceso de contribución proporciona reconocimiento a los mantenedores y les permite proporcionar comentarios iniciales sobre los cambios.

1. Ve al repositorio bifurcado en GitHub. Por ejemplo, http://github.com/YOUR-USERNAME/docs.
2. Deberías ver un mensaje "Compare & pull request" para la rama insertada recientemente. Haga clic en él.
3. De lo contrario, ve a la pestaña "Pull requests" y haz clic en "New pull request".
4. Asegúrate de que el repositorio base sea github/docs y que la rama base sea su rama principal (por ejemplo, main).
5. Asegúrate de que el repositorio head sea tu bifurcación (YOUR-USERNAME/docs) y que la rama de comparación sea tu rama.
6. Escribe un título y una descripción para tu solicitud de extracción. En la descripción, haz referencia a la incidencia que cerrará la solicitud de cambios. Por ejemplo, Closes: #15. Esto proporcionará contexto para la solicitud de cambios y cerrará automáticamente la incidencia una vez que se fusione la solicitud de cambios.

Trabajo con mantenedores de proyectos

Una vez que se haya enviado la solicitud de cambios, el siguiente paso es que un mantenedor del proyecto revise y proporcione comentarios. Los mantenedores de proyectos pueden solicitar cambios para que coincidan con el estilo o la arquitectura del código base, lo que a veces requiere que refactorices partes sustanciales de tu trabajo.

• Cuando lleguen comentarios sobre la solicitud de cambios, responde con prontitud y profesionalmente, incluso si las críticas te parecen duras. Normalmente, los mantenedores se centran en la calidad del código.
• Si se solicitan cambios para tu solicitud de cambios, no abras una nueva para abordarlos. Mantener abierta la solicitud de cambios existente y realizar cambios en ella ayuda a evitar que los mantenedores pierdan contexto.
• Si no se aborda tu solicitud de cambios durante semanas, realiza el seguimiento con un comentario que solicite comentarios. No menciones directamente los identificadores de los mantenedores. A menudo, los mantenedores equilibran el trabajo de código abierto con sus responsabilidades a tiempo completo y comprender sus restricciones de tiempo fomenta una mejor colaboración.
• Si tu contribución no se acepta, pide a los mantenedores comentarios para que puedas tener ese contexto la próxima vez que quieras realizar una contribución.

Pasos siguientes

Ahora sabes cómo identificar las incidencias adecuadas en los que trabajar, crear contribuciones que los mantenedores quieran combinar y cómo navegar por el proceso de revisión de solicitudes de cambios. La comunidad de código abierto de GitHub está lista para recibir tu perspectiva y aptitudes únicas. Busca un nuevo proyecto que te atraiga, identifica una incidencia en la que trabajar y empieza a contribuir.