Colaborar con otras personas mejorará tu paquete, y si les das a algunas de ellas rol de autoría y permisos de escritura en el repositorio, tu paquete se desarrollará de forma más sostenible. Además, ¡trabajar en equipo puede ser muy agradable!
Además de estos consejos, en su mayoría técnicos, es importante recordar que hay que ser amable y tener en cuenta la perspectiva de las otras personas, especialmente cuando sus prioridades difieren de las tuyas.
11.1 Haz que tu repositorio sea accesible a las contribuciones y la colaboración
11.1.1 Código de conducta
Tras el traslado a nuestra organización de GitHub, el Código de Conducta de rOpenSci se aplicará a tu proyecto. Por favor, añade este texto al README
Ten en cuenta que este paquete se publica con un [Código de Conducta para contribuciones](https://ropensci.org/code-of-conduct/). Al contribuir a este proyecto, te comprometes a cumplir sus condiciones.
Y eliminar el código de conducta actual del paquete, si lo hubiera.
11.1.2 Guía de contribución
Puedes utilizar guías de issues, pull request y de contribución. Tener un archivo de contribución como .github/CONTRIBUTING.md o docs/CONTRIBUTING.md es obligatorio. Una forma fácil de insertar una plantilla para una guía de contribución es la función use_tidy_contributing() del paquete usethis que inserta esta plantilla como .github/CONTRIBUTING.md. Un ejemplo más extenso es esta plantilla de Peter Desmet o las completas páginas wiki de GitHub para el paquete mlr3. Estas y otras plantillas generalmente tendrán que ser modificadas para su uso con un paquete de rOpenSci, en particular haciendo referencia y enlazando con nuestro Código de Conducta como se describe en otra sección de este libro. Modificar una guía de contribución genérica para añadir un toque propio también tiende a hacer que parezca menos impersonal y más sincera. Las preferencias personales en una guía de contribución incluyen
Creación de una cuenta de prueba, tests simulados, enlace a documentación externa.
rOpenSci recomienda que las guías de contribución incluyan una declaración del ciclo de vida, que aclare la visión y las expectativas para el desarrollo futuro del paquete, como en este ejemplo. Los paquetes estadísticos deben tener una declaración de ciclo de vida, como se especifica en Normas Generales de Estadística G1.2. Ese enlace proporciona una plantilla para una declaración de ciclo de vida sencilla. Los archivos CONTRIBUTING.md también pueden describir cómo se reconocen las contribuciones (ver esta sección).
Te animamos a que dirijas las consultas y comentarios que no sean informes de errores o pedidos de nueva funcionalidad al foro de rOpenSci después de asegurarte de que verás esas preguntas en el foro. El foro puede usarse para hacer preguntas sobre cómo usar el paquete e informar de sus casos de uso, y puedes suscribirte a categorías y etiquetas individuales para recibir notificaciones sobre tu paquete. No dudes en mencionar esto en los documentos de tu paquete, ya sea en la guía de contribución o en la plantilla de issue. Pide etiquetar las publicaciones con el nombre del paquete.
Utilizando las funciones de GitHub en torno a los issues puedes hacer que sean más encontrables y que tu hoja de ruta sea pública.
11.1.3.1 Plantillas de issue
Puedes utilizar una o varias plantilla(s) de issue para que los informes de errores o pedido de funcionalidad sean más fáciles de completar. Cuando hay varias plantillas de issue, éstas se muestran en un menú al hacer click en el botón de “nuevo issue”
Incluso puedes configurar una de las opciones para que apunte a algún lugar fuera de tu repositorio (por ejemplo, un foro de discusión).
Puedes resaltar hasta 3 issues por repositorio que aparecerán en la parte superior de tu gestor de issues como bonitas tarjetas. Puede ayudar a anunciar cuáles son tus prioridades.
11.1.3.4 Hitos
Puedes crear hitos y asignarles issues, lo que ayuda a ver lo que planeas para la próxima versión de tu paquete, por ejemplo.
11.1.4 Comunicación
Puedes dirigir a quienes usan tu paquete al foro de rOpenSci, si lo supervisas, o habilitar Discusiones de GitHub para el repositorio de tu paquete. Las discusiones de GitHub pueden convertirse en issues si fuera necesario (y al revés, los issues pueden convertirse en discusiones).
11.2 Trabajar en equipo
Lo primero lo primero: ¡estate al tanto de tu repositorio de GitHub!
no te olvides de vigilar tu repositorio de GitHub para que te notifiquen los issues o pull requests (si trabajas por períodos, puedes informarlo en la guía de contribución).
no olvides hacer push de las actualizaciones que tengas localmente.
desactiva los test que fallan si no puedes arreglarlos, ya que crean ruido en los pull requests que pueden desconcertar quienes comienzan a colaborar.
11.2.1 Incorporación de miembros al equipo
No hay una regla general en rOpenSci sobre cómo debes incorporar a quienes colaboran en tu paquete al equipo. Deberías ir dándoles más derechos en el repositorio a medida que ganes confianza, y definitivamente deberías reconocer las contribuciones (ver esta sección).
Puedes pedir a las nuevas personas que se incorporen que hagan PRs (ver la siguiente sección para evaluar un PR localmente, es decir, más allá de las comprobaciones de CI) a dev/main y evaluarlos antes de aceptarlos, y después de un tiempo dejar que hagan push a main. También puede que quieras mantener un sistema de revisión de PRs… ¡incluso para ti una vez que tengas miembros de equipo!
Jim Hester ofrece un posible modelo de incorporación de miembros de equipo en su repositorio de lintr.
Si tu problema es reclutar nuevas personas, puedes publicar una convocatoria abierta como la de Jim Hester en Twitter, GitHub y, como responsable de un paquete de rOpenSci, puedes pedir ayuda en el Slack de rOpenSci y solicitar al equipo de rOpenSci ideas para reclutar ayuda.
11.2.2 Trabajar con otras personas (Incluyéndote a tí en el futuro)
Las branches son baratas. Utilízalas mucho cuando desarrolles funciones, pruebes nuevas ideas o arregles problemas.
Si sigues el desarrollo troncal, “agregarás pequeñas y frecuentes actualizaciones” a tu branch principal. Ver también la documentación del Flujo de GitHub y el flujo de GitLab. Es posible que quieras incrementar los números de versión (en DESCRIPTION) frecuentemente. Un aspecto particular del trabajo con otras personas es la revisión de pull requests. Pueden ver algunas guías útiles en:
Si una persona contribuye a tu repositorio, considera añadirla en el archivo DESCRIPTION, con el rol de contribución (“ctb”) para pequeñas contribuciones o autoría (“aut”) para contribuciones mayores. Tradicionalmente, cuando se cita un paquete en una publicación científica, sólo se enumeran a quienes están como “aut”, no quienes están como “ctb”. Los sitios web creados con pkgdown listan en la página de inicio sólo a las personas con rol de autoría (“aut”). El resto están listadas en una página dedicada.
Como mínimo, considera la posibilidad de añadir el nombre de quien contribuyó cerca de la línea de la función o corrección de errores en el archivo NEWS.md.
Te recomendamos reconozcas estas contribuciones generosamente, ya que es algo agradable y porque hará que sea más probable que la gente vuelva a contribuir a tu paquete o a otros repos de la organización.
Como recordatorio de nuestra guía de empaquetado si tu paquete fue revisado y crees que quienes lo hicieron han hecho una contribución sustancial al desarrollo de tu paquete, puedes usar el campo Authors@R con el rol de revisión ("rev"), así
persona("Bea", "Hernández", rol = "rev",
comment = "Bea revisó el paquete (v. X.X.XX) para rOpenSci, véase <https://github.com/ropensci/software-review/issues/116>"),
Por favor, no incluyas a quienes se encargaron de la edición. ¡Tu participación y contribución a rOpenSci es suficiente agradecimiento!
11.2.4 Bienvenida a nuevas personas en rOpenSci
Si das a alguien permisos de escritura en el repositorio
por favor, ponte en contacto con un miembro del quipo para invitar a la organización GitHub “ropensci” de rOpenSci a este nuevo miembro del equipo (en lugar de una colaboración externa)
ponte en contacto con quien gestiona la comunidad de rOpenSci o con otro miembro del equipo para que el nuevo miembro pueda ser invitado al espacio de trabajo de Slack de rOpenSci.