/
maintenance_collaboration.es.Rmd
174 lines (109 loc) · 15.3 KB
/
maintenance_collaboration.es.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
# Guía de colaboración {#collaboration}
```{block, type="summaryblock"}
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](https://help.github.com/articles/repository-permission-levels-for-an-organization/), tu paquete se desarrollará de forma más sostenible.
Además, ¡trabajar en equipo puede ser muy agradable!
Los consejos para colaborar en este capítulo están divididos en una sección sobre [cómo hacer que la infraestructura de tu repo sea accessible para la contribución y la colaboración](#friendlyfiles) (código de conducta, directrices de contribución, etiquetas de *issues*) y [una sección sobre cómo colaborar con nuevas personas que quieran contribuir](#workingcollaborators), en particular en el contexto de la organización "ropensci" de rOpenSci en GitHub.
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.
```
## Haz que tu repositorio sea accesible a las contribuciones y la colaboración {#friendlyfiles}
### Código de conducta {#coc-file}
Tras el traslado a nuestra organización de GitHub, [el Código de Conducta de rOpenSci](https://ropensci.org/code-of-conduct/) se aplicará a tu proyecto.
Por favor, añade este texto al *README*
```markdown
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.
### Guía de contribución {#contributing-guide}
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`](https://usethis.r-lib.org/reference/tidyverse.html) que inserta [esta plantilla](https://github.com/r-lib/usethis/blob/main/inst/templates/tidy-contributing.md) como `.github/CONTRIBUTING.md`.
Un ejemplo más extenso es [esta plantilla de Peter Desmet](https://gist.github.com/peterdesmet/e90a1b0dc17af6c12daf6e8b2f044e7c) o las completas [páginas wiki de GitHub para el paquete mlr3](https://github.com/mlr-org/mlr3/wiki).
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](https://ropensci.org/codigo-de-conducta/) como se describe en otra sección [de este libro](#code-of-conduct).
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
- Preferencias de estilo. Sin embargo, puedes preferir que el estilo sea uno automático (a través de [lintr](https://github.com/jimhester/lintr) o [styler](https://styler.r-lib.org/)) o bien [arreglar el estilo de código por tu cuenta](https://github.com/rstudio/blogdown/pull/432#pullrequestreview-368391904) especialmente si no utilizas un estilo de código popular como el [estilo de código tidyverse](https://style.tidyverse.org/).
- Infraestructura, como roxygen2.
- Preferencias de flujo de trabajo. Por ejemplo, abrir un *issue* antes de hacer un *pull request*.
- Una declaración de alcance, como [en el paquete skimr](https://github.com/ropensci/skimr/blob/main/.github/CONTRIBUTING.md#understanding-the-scope-of-skimr).
- 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](https://github.com/ecohealthalliance/fasterize/blob/master/CONTRIBUTING.md#roadmap).
Los paquetes estadísticos deben tener una declaración de ciclo de vida, como se especifica en [Normas Generales de Estadística G1.2](https://stats-devguide.ropensci.org/standards.html#documentation).
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](#attributions)).
Te animamos a que dirijas las consultas y comentarios que no sean informes de errores o pedidos de nueva funcionalidad al [foro de rOpenSci](https://discuss.ropensci.org/) 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.
Una vez que un *pull request* está más cerca de ser aceptado, puedes utilizar [un flujo de trabajo de *GitHub Actions PR* para aplicar el estilo al código con styler](https://github.com/r-lib/actions/blob/master/examples/pr-commands.yaml).
### Gestión de issues {#issue-management}
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.
#### Plantillas de issue {#issue-templates}
Puedes utilizar una o varias [plantilla(s) de *issue*](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository#creating-issue-templates=) 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](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository#configuring-the-template-chooser=) para que apunte a algún lugar fuera de tu repositorio (por ejemplo, un foro de discusión).
Consulta la [documentación de GitHub (en inglés)](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository).
#### Etiquetado de issues {#issue-labelling}
Puedes utilizar etiquetas como "se necesita ayuda" y "buen primer *issue*" para que seas más fáciles de encontrar, incluso por gente que llega por primera vez a tu repo.
Consulta [este artículo de GitHub (en inglés)](https://help.github.com/articles/helping-new-contributors-find-your-project-with-labels/).
También puedes utilizar la etiqueta "principiante".
Consulta [ejemplos de issues para principiantes en todos los repos de ropensci](https://github.com/search?q=user%3Aropensci+user%3Aropenscilabs+label%3ABeginner+state%3Aopen&type=Issues).
#### Resaltado de issues {#pinning-issues}
Puedes [resaltar hasta 3 issues por repositorio](https://docs.github.com/en/articles/pinning-an-issue-to-your-repository) que aparecerán en la parte superior de tu gestor de *issues* como bonitas tarjetas.
Puede ayudar a anunciar cuáles son tus prioridades.
#### Hitos {#milestones}
Puedes [crear hitos](https://docs.github.com/en/issues/using-labels-and-milestones-to-track-work/about-milestones) y asignarles *issues*, lo que ayuda a ver lo que planeas para la próxima versión de tu paquete, por ejemplo.
### Comunicación {#communication-with-users}
Puedes dirigir a quienes usan tu paquete al foro de rOpenSci, si lo supervisas, o habilitar [Discusiones de GitHub](https://docs.github.com/en/discussions) 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).
## Trabajar en equipo {#workingcollaborators}
Lo primero lo primero: ¡estate al tanto de tu repositorio de GitHub!
- no te olvides de [**vigilar tu repositorio de GitHub**](https://docs.github.com/en/github/managing-subscriptions-and-notifications-on-github/managing-subscriptions-for-activity-on-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.
### Incorporación de miembros al equipo {#onboarding-collaborators}
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](#attributions)).
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`](https://github.com/jimhester/lintr/issues/318).
Si tu problema es *reclutar* nuevas personas, puedes publicar una convocatoria abierta como la de Jim Hester [en Twitter](https://twitter.com/jimhester_/status/997109466674819074), [GitHub](https://github.com/jimhester/lintr/issues/318) 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.
### Trabajar con otras personas (Incluyéndote a tí en el futuro) {#git-workflow}
[Las *branches*](https://happygitwithr.com/git-branches.html) son baratas.
Utilízalas mucho cuando desarrolles funciones, pruebes nuevas ideas o arregles problemas.
Si sigues el [desarrollo troncal](https://www.atlassian.com/continuous-delivery/continuous-integration/trunk-based-development), "agregarás pequeñas y frecuentes actualizaciones" a tu *branch* principal.
Ver también la documentación del [Flujo de GitHub](https://docs.github.com/en/get-started/quickstart/github-flow) y el [flujo de GitLab](https://docs.gitlab.com/ee/topics/gitlab_flow.html).
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:
- [*The Art of Giving and Receiving Code Reviews (Gracefully)* (El arte de dar y recibir revisiones de código (con elegancia)), por Alex Hill](https://www.alexandra-hill.com/2018/06/25/the-art-of-giving-and-receiving-code-reviews/)
- [Documentación de GitHub sobre revisiones de PR](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews)
Puedes modificar la configuración de tu repositorio de GitHub,
por ejemplo [requeriendo revisiones de *pull requests* antes de aceptarlas e incorporarlas](https://docs.github.com/es/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/about-protected-branches#require-pull-request-reviews-before-merging).
También puedes consultar la documentación [acerca de propiedad sobre código](https://docs.github.com/es/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners).
Para hacer y revisar *pull requests* recomendamos [explorar las funciones del paquete usethis](https://usethis.r-lib.org/articles/pr-functions.html).
Para tu configuración "git remote" consulta [*Happy Git with R*](https://happygitwithr.com/common-remote-setups.html).
También es útil la sección [Useful Git patterns for real life](https://happygitwithr.com/workflows-intro.html) en el mismo libro.
### Atribuye con generosidad {#attributions}
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](#news).
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](#building) 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>"),
```
Sólo incluye a quienes hicieron la revisión con su consentimiento.
Lee más en [esta entrada del blog *Thanking Your Reviewers: Gratitude through Semantic Metadata* (Agradeciendo a quienes revisaron tu paquete: La gratitud a través de los metadatos semánticos)](https://ropensci.org/blog/2018/03/16/thanking-reviewers-in-metadata/).
Ten en cuenta que 'rev' generará una NOTA de CRAN a menos que el paquete esté construido con R v3.5. Asegúrate de que utilizas la ultima versión de `roxygen2` en CRAN.
Por favor, no incluyas a quienes se encargaron de la edición.
¡Tu participación y contribución a rOpenSci es suficiente agradecimiento!
### Bienvenida a nuevas personas en rOpenSci {#welcoming-collaborators-to-ropensci}
Si das a alguien permisos de escritura en el repositorio
- por favor, ponte en contacto con un [miembro del quipo](https://ropensci.org/about#team) para **invitar a la organización GitHub "ropensci" de rOpenSci** a este nuevo miembro del equipo (en lugar de una [colaboración externa](https://help.github.com/articles/repository-permission-levels-for-an-organization/#outside-collaborators))
- ponte en contacto con quien gestiona la comunidad de rOpenSci [o con otro miembro del equipo](https://ropensci.org/about#team) para que el nuevo miembro pueda ser **invitado al espacio de trabajo de Slack de rOpenSci**.
## Otros recursos {#further-resources}
- Llamada comunitaria de rOpenSci [*Set Up Your Package to Foster a Community* (Configura tu paquete para fomentar una comunidad)](https://ropensci.org/commcalls/apr2021-pkg-community/).
- Para reutilizar respuestas amables y habituales, considera las [respuestas guardadas](https://docs.github.com/en/github/writing-on-github/working-with-saved-replies/using-saved-replies).