Guía de contribución al open source

El software open source impulsa la web moderna, y contribuir de vuelta es una de las cosas más gratificantes que puede hacer un desarrollador. Ya sea que corrija una errata en la documentación o implemente una funcionalidad importante, cada contribución cuenta.

Esta guía cubre el lado práctico: elegir un proyecto, leerlo antes de escribir código, preparar un pull request fácil de aceptar y gestionar la revisión.

Encontrar el proyecto adecuado

Empiece por las herramientas que ya usa. Tendrá contexto sobre el problema y una motivación genuina para mejorar algo que afecta a su trabajo diario. Busque repositorios con un archivo CONTRIBUTING.md, issue trackers activos y maintainers que respondan a los issues en un plazo razonable.

Los buenos issues para empezar suelen estar etiquetados como “good first issue”, “help wanted” o “beginner friendly”. Estos issues están seleccionados específicamente para recién llegados y normalmente incluyen contexto adicional para ayudarle a comenzar.

Algunas señales rápidas le indican si un proyecto es un buen lugar donde invertir su tiempo:

• Pull requests fusionados recientemente de personas ajenas al equipo principal. Demuestra que las contribuciones externas realmente se aceptan.
• Una licencia clara en un archivo LICENSE. Sin ella, no tiene ningún derecho definido para usar o modificar el código.
• Un código de conducta y un tono respetuoso en las discusiones de los issues.
• Una suite de tests que funcione y que pueda ejecutar localmente. Es mucho más fácil cambiar código con seguridad cuando puede verificarlo.

Lea antes de escribir

Antes de tocar el código, dedique un tiempo a la documentación del propio proyecto. CONTRIBUTING.md suele responder a las preguntas que los maintainers están cansados de repetir: cómo configurar el entorno de desarrollo, a qué rama apuntar, qué formato deben tener los commits y si necesita firmar un Contributor License Agreement o añadir a sus commits una firma Developer Certificate of Origin.

Después, lea el issue en el que quiere trabajar, incluidos todos los comentarios. Puede que ya tenga un enfoque propuesto, uno descartado o que otra persona esté trabajando en él. Si el cambio es algo más que una corrección pequeña, deje un comentario describiendo lo que piensa hacer y espere a que un maintainer esté de acuerdo. Diez minutos de discusión pueden ahorrarle un fin de semana dedicado a un pull request que no encaja con la dirección del proyecto.

Configurar su fork

Haga un fork del repositorio y cree una rama de funcionalidad con un nombre descriptivo. Mantenga una referencia al repositorio original para poder mantenerse al día:

git clone https://github.com/<your-username>/<project>.git
cd <project>
git remote add upstream https://github.com/<owner>/<project>.git
git switch -c fix/date-parsing-timezone

Ejecute los comandos de instalación, compilación y tests del proyecto antes de cambiar nada. Si los tests fallan en un checkout limpio, le conviene saberlo ahora, no después de haber hecho cambios y mientras se pregunta si rompió algo.

Cuando la rama principal avance mientras usted trabaja, actualice su rama:

git fetch upstream
git rebase upstream/main

Algunos proyectos prefieren merge en lugar de rebase; siga lo que indique CONTRIBUTING.md.

Su primera contribución

Escriba su código siguiendo los estándares de codificación del proyecto e incluya tests cuando corresponda. Mantenga sus cambios acotados: un pull request que aborda un solo issue es mucho más fácil de revisar que uno que aborda cinco.

Mantener el foco también significa resistirse a las limpiezas cercanas. Si nota un formato inconsistente o una función que habría escrito de otra manera, déjela como está o abra un pull request aparte. Los cambios no relacionados hacen que el diff sea más difícil de leer y que la revisión sea más lenta.

En las correcciones de errores, lo más convincente que puede incluir es un test que falle antes de su cambio y pase después. Demuestra que el error existía, muestra que su corrección lo resuelve y evita que vuelva a aparecer.

Haga también que sus commits sean legibles. Un buen mensaje de commit tiene una línea de resumen breve en modo imperativo y, cuando ayuda, un cuerpo que explica por qué el cambio era necesario:

Fix timezone offset when parsing ISO dates

Dates without an explicit offset were parsed as UTC, which shifted
event times for users in other zones. Parse them as local time to
match the documented behaviour.

Ejecute el linter y el formateador del proyecto antes de hacer push. Muchos proyectos los comprueban automáticamente, y una comprobación fallida es una razón fácil para que un revisor deje su pull request de lado.

Escribir un buen pull request

Escriba una descripción clara del pull request que explique el problema, su solución y las alternativas que consideró. Enlace el issue correspondiente. Si su cambio afecta a la interfaz de usuario, incluya capturas de pantalla.

Una estructura que funciona para la mayoría de los cambios:

1. ¿Qué problema resuelve? Una o dos frases, con un enlace al issue.
2. ¿Qué ha cambiado? Un breve resumen del enfoque, sobre todo de lo que no sea evidente.
3. ¿Cómo lo ha probado? Los comandos que ejecutó y cualquier paso manual que un revisor pueda repetir.
4. ¿Qué queda pendiente? Limitaciones conocidas o trabajo posterior que decidió no incluir.

Si el proyecto tiene una plantilla de pull request, complete todas las secciones. Abrir un pull request en borrador es una buena manera de obtener comentarios tempranos sobre la dirección antes de pulir los detalles.

Etiqueta en la revisión de código

Tenga paciencia con los maintainers. A menudo dedican su tiempo de forma voluntaria. Responda a los comentarios de revisión con amabilidad, haga preguntas aclaratorias cuando un comentario no esté claro y aplique los cambios solicitados con prontitud. Si un maintainer sugiere un enfoque distinto, intente entender su razonamiento antes de oponerse.

Algunos hábitos hacen que la revisión fluya mejor:

• Responda a cada comentario, aunque sea con un breve “hecho”, para que el revisor sepa que lo vio.
• Suba commits de seguimiento en lugar de hacer force-push durante la revisión, salvo que el proyecto indique lo contrario. Así los revisores ven solo lo que cambió desde su última revisión.
• No se lo tome como algo personal. Los revisores evalúan el cambio, no a usted, y mantendrán ese código mucho después de que su pull request se haya fusionado.
• Haga un seguimiento cortés si pasan una o dos semanas sin respuesta. Un único comentario breve está bien; los recordatorios repetidos, no.

A veces la respuesta es no. Un proyecto puede rechazar un cambio porque no encaja con su hoja de ruta o porque añadiría una carga de mantenimiento. Es un resultado legítimo, y la forma en que responda determinará cómo se recibirá su próxima contribución.

Más allá del código

Las contribuciones no se limitan al código. Las mejoras en la documentación, los reportes de errores con pasos de reproducción claros, los recursos de diseño y el apoyo a la comunidad en las discusiones de los issues son formas valiosas de contribuir.

Un buen reporte de error es una contribución por derecho propio. Incluya la versión que usa, su entorno, los pasos exactos para reproducirlo, lo que esperaba y lo que ocurrió en su lugar. Una reproducción mínima, como un repositorio pequeño o un fragmento de código breve que muestre el problema de forma aislada, a menudo hace más para que se corrija un error que cualquier otra cosa.

Siga adelante

La comunidad open source prospera cuando las personas devuelven algo. Empiece poco a poco, aprenda cómo funcionan las cosas y asuma gradualmente retos mayores. Cada pull request fusionado le enseña más sobre el código y genera confianza con sus maintainers, y esa confianza es lo que con el tiempo se convierte en trabajos de mayor envergadura. Sus contribuciones son bienvenidas.