6  Guía para quienes crean paquetes

Esta guía condensa el proceso de revisión por pares desde el punto de vista de quienes crean paquetes.

6.1 Planificar un envío (o una consulta previa al envío)

  • ¿Esperas mantener tu paquete durante al menos 2 años, o poder encontrar a otra persona para mantenerlo?
  • Consulta nuestras políticas para evaluar si tu paquete cumple los criterios para ser incluido en nuestro conjunto de paquetes y no se superpone con otros.
  • Por favor, considera cuál es el mejor momento en el desarrollo de tu paquete para presentarlo. Tu paquete debe estar lo suficientemente maduro como para que quienes lo revisen puedan evaluar todos los aspectos esenciales, pero ten en cuenta que la revisión puede resultar en cambios importantes.
  • Te recomendamos fuertemente que envíes tu paquete para su revisión antes de publicarlo en CRAN o enviar un artículo de software que describa el paquete a una revista. Las devoluciones de las revisiones pueden dar pie a importantes mejoras y actualizaciones de tu paquete, incluso cambiar el nombre o modificaciones incompatibles con versiones previas.
  • No envíes tu paquete para su revisión mientras éste o un artículo científico asociado también esté siendo revisado en otro lugar, ya que esto puede dar lugar a recomendaciones incompatibles.
  • Ten en cuenta también el tiempo y el esfuerzo necesarios para responder a las revisiones: piensa en tu disponibilidad o en la de quienes colaboran con tu paquete en las semanas y meses siguientes al envío. Ten en cuenta que las revisiones son realizadas por personas voluntarias, y te pedimos que respetes su tiempo y esfuerzo respondiendo puntual y respetuosamente.
  • Si utilizas etiquetas de repostatus.org (que recomendamos), envía tu paquete cuando esté listo para obtener la etiqueta Active en vez de WIP. Si utilizas etiquetas de ciclo de vida, el envío debe producirse cuando el paquete esté al menos en el estado Maturing.
  • Para cualquier envío o consulta previa al envío, el README de tu paquete debería proporcionar suficiente información sobre el mismo (objetivos, uso, paquetes similares) para que quienes revisan el paquete puedan evaluar su alcance sin tener que instalarlo. Mejor aún, crea un sitio web de pkgdown para que puedan evaluar las funcionalidads detalladamente en línea.
  • En la fase de envío, todas las funciones principales deben ser lo suficientemente estables como para estar completamente documentadas y testeadas. El README tiene que dar una buena impresión de tu paquete.
  • El archivo README debe esforzarse por explicar las funcionalidades y los objetivos de tu paquete asumiendo poco o ningún conocimiento del dominio. Además, debe aclarar todos los temas técnicos, incluidas las referencias a otros software.
  • Tu paquete seguirá evolucionando después de la revisión, el capítulo sobre Evolución de paquetes proporciona orientación sobre el tema.

6.2 Preparación para el envío

  • Lee y sigue nuestra guía de estilo para paquetes y nuestra guía para la revisión para asegurarte de que tu paquete cumple nuestros criterios de estilo y calidad.
  • No dudes en hacer cualquier pregunta sobre el proceso en general, o sobre tu paquete en particular en nuestro foro de discusión.
  • Todos los envíos son revisados automáticamente por nuestro propio sistema para garantizar que los paquetes sigan nuestras directrices. Se espera que hayas corrido la función pkgcheck localmente para confirmar que el paquete está listo para ser enviado. Otra forma aún más fácil de asegurarse de que un paquete está listo para su envío es utilizar la acción de GitHub pkgcheck para ejecutar pkgcheck como una Acción de GitHub, como se describe en esta publicación en nuestro blog.
  • Si tu paquete requiere dependencias inusuales del sistema (ver Guía de Empaquetado para que nuestra Acción de GitHub pase, por favor envíe un pull request añadiéndolas a nuestro Dockerfile base.
  • Si hay algún test de pkgcheck que tu paquete no pueda aprobar, explica los motivos en la plantilla de envío.
  • Si crees que tu paquete es relevante para el Journal of Open Source Software (JOSS), no lo sometas a consideración de JOSS hasta que haya finalizado el proceso de revisión de rOpenSci: si el equipo de edición de JOSS considera que tu paquete está dentro de su ámbito de aplicación, sólo se revisará el breve artículo que lo acompaña (pero no el software que habrá sido revisado por rOpenSci en ese momento). No todos los paquetes de rOpenSci pueden aplicar a JOSS.

6.3 El proceso de envío

  • Para presentar tu paquete a revisión tienes que abrir un nuevo issue en el repositorio de revisión de software y completar la plantilla.
  • La plantilla comienza con una sección que incluye varias variables de estilo HTML (<!---variable--->). Éstas son utilizadas por nuestro bot (ropensci-review-bot) y no deben modificarse. Los valores de las variables deben completarse ente los puntos de inicio y fin, así:
<!---variable--->insertar valor aquí<!---end-variable>
  • La comunicación entre quines envian el paquete, quienes lo revisen y quienes hagan la edición se dará principalmente en GitHub, para que el issue de revisión sirva de registro completo de la misma. Puedes contactarte con quien se encarga de la edición por correo electrónico o Slack si es necesario realizar una consulta privada (por ejemplo, preguntar cómo responder a una pregunta de quien está haciendo la revisión). No te pongas en contacto con quienes revisan tu paquete fuera del issue sin antes preguntarles, dentro del mismo, si están de acuerdo con ello.
  • Cuando envíes un paquete, por favor asegúrate de tener configuradas las notificaciones de GitHub para que no te pierdas ningún comentario.
  • Los paquetes se checkean automáticamente al ser enviados con nuestro sistema pkgcheck, el cual confirmará si está listo para ser revisado o no.
  • Los paquetes enviados pueden estar en la rama main/default, o en cualquier otra rama no predeterminada. En este último caso, es recomendable, aunque no obligatorio, enviar el paquete a través de una rama dedicada llamada ropensci-software-review.

6.4 El proceso de revisión

  • Una persona realizará la edición y revisará tu envío en un plazo de 5 días laborables y te responderá con los siguientes pasos a seguir. Puede asignar el paquete a personas para que lo revisen, solicitar que el paquete se actualice para cumplir los criterios mínimos antes de la revisión, o rechazar el paquete porque el mismo no encaja en rOpenSci o porque se solapa con uno ya existente.
  • Si tu paquete cumple con los criterios mínimos, se le asignará de 1 a 3 personas para hacer la revisión, a quienes se les pedirá proporcionar revisiones en forma de comentarios sobre tu issue en un plazo máximo de 3 semanas.
  • Te pedimos que respondas a estos comentarios en un plazo máximo de 2 semanas desde la última revisión presentada, pero puedes actualizar tu paquete o responder en cualquier momento. Tu respuesta debe incluir un enlace a la actualización del archivo NEWS.md de tu paquete. Aquí tienes un ejemplo de respuesta. Fomentamos las conversaciones continuas entre quienes envían el paquete y quienes lo revisan. Consulta la guía de revisión para más detalles.
  • Si algún cambio en el paquete puede modificar los resultados de pkgcheck, se puede solicitar un nuevo chequeo con el comando @ropensci-review-bot check package.
  • Por favor, notifícanos inmediatamente si ya no puedes mantener tu paquete o responder a las revisiones. En ese caso, se espera que retractes el envío o que encuentres responsables alternativos para mantener del paquete. También puedes discutir los problemas de mantenimiento en el Slack de rOpenSci.
  • Una vez que tu paquete sea aceptado, te proporcionaremos más instrucciones sobre la transferencia de tu repositorio al repositorio de rOpenSci.

Nuestro código de conducta es obligatorio para la participación en nuestro proceso de revisión.