start policy updates on ai tool usage #1006
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -482,6 +482,14 @@ a sustentabilidade de longo prazo do seu pacote. Isso também | |
|
|
||
| - Os arquivos de origem do seu pacote devem estar sob controle de versão, mais especificamente rastreados com [Git](https://happygitwithr.com/). Você pode achar o [pacote gert](https://docs.ropensci.org/gert/) relevante, bem como algumas das funções do [pacote usethis relacionadas ao Git/GitHub](https://usethis.r-lib.org/reference/index.html#section-git-and-github); no entanto, você pode usar o git como quiser. | ||
|
|
||
|
|
||
| - Commits pequenos e informativos no Git permitem compreender melhor e depurar um projeto. Não agrupe muitas alterações não relacionadas em um único commit; evite usar mensagens de commit sem sentido, como “atualização” ou “commit”. Não exigimos um histórico de Git impecável, mas recomendamos fortemente que você se esforce para mantê-lo organizado. Recursos úteis: | ||
| - [“Escreva commits melhores, construa projetos melhores”](https://github.blog/developer-skills/github/write-better-commits-build-better-projects/); | ||
| - [“Por que você precisa de commits pequenos e informativos no Git”](https://masalmon.eu/2024/06/03/small-commits/); | ||
| - [“Descubra seu jeito de criar um bom histórico do Git”](https://masalmon.eu/2024/06/11/rewrite-git-history/); | ||
| - [O pacote R saperlipopette para praticar o uso do Git](https://docs.ropensci.org/saperlipopette/). | ||
|
|
||
|
|
||
| - O nome da ramificação (*branch*) padrão não deve ser `master`, pois isso pode ser ofensivo para algumas pessoas. Consulte a seção [do projeto Git e da Software Freedom Conservancy](https://sfconservancy.org/news/2020/jun/23/gitbranchname/) para obter mais contexto. É uma prática geral nomear uma ramificação padrão `main`, embora outros nomes também possam ser usados. Consulte a postagem do blog do tidyverse ["Renomeando a ramificação padrão"](https://www.tidyverse.org/blog/2021/10/renaming-default-branch/) para saber mais sobre como usar essa funcionalidade para ajudar a renomear as ramificações padrão. | ||
|
|
||
| - Certifique-se de listar arquivos desnecessários, como `.DS_Store`, no arquivo .gitignore. Você pode achar a função [`usethis::git_vaccinate()`](https://usethis.r-lib.org/reference/git_vaccinate.html) e o [pacote gitignore](https://docs.ropensci.org/gitignore/) relevantes. | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -38,6 +38,22 @@ This concise guide presents the software peer review process for you as a packag | |
| - Your README file should strive to explain your package's functionality and aims, assuming readers have little to no domain knowledge. All technical tems, including references to other software, should be clarified. | ||
| - Your package will continue to evolve after review, the chapter on *Package evolution* [provides guidance about the topic](#evolution). | ||
|
|
||
| ### Use of generative AI tools | ||
|
|
||
| - The use of generative AI tools is acceptable in packages submitted for peer review, as described in [our initial blog post](https://ropensci.org/blog/2026/02/26/ropensci-ai-policy/). | ||
| - As stated in [our general policies](#policies-ai), we require all submitting authors to provide details on any usage of generative AI tools in package documentation, generally in either README files or contributing guides. | ||
| - Extended descriptions of AI tool usage or design decisions may also be held in separate documents, in which case these should be linked directly from the README or contributing guide. | ||
| - An example is [the `HydraR` package](https://apaf-bioinformatics.github.io/HydraR/#robot-use-of-generative-ai), which provides link in the main README to [agents.md](https://apaf-bioinformatics.github.io/HydraR/agents.html) and [DESIGN.md](https://apaf-bioinformatics.github.io/HydraR/DESIGN.html) files. | ||
| - A very general rule-of-thumb is the greater the use of generative AI tools in a package, the more we will expect tool use to be documented within the software itself. | ||
| - We suggest using AI tools in ways that record decisions guiding development processes and outputs within the software itself. | ||
| - Examples of such tools range from [GitHub's "spec-kit" for specification-driven development](https://github.com/github/spec-kit) and [our own experimental tool to document software design decisions](https://github.com/ropensci-review-tools/designlens). | ||
|
maelle marked this conversation as resolved.
|
||
| - These all share the common pattern of producing additional artefacts which document decisions and processes of development alongside the software itself. | ||
|
|
||
| #### The importance of Git logs | ||
|
|
||
| - The Git log is an important source of insight into design history. Refer to our [version control](#version-control) guidance, which contains resources about creating informative Git logs. | ||
| - While we place no current minimal limits on Git log size, we do note that [JOSS now requires at least six months of public commit history](https://joss.readthedocs.io/en/latest/submitting.html#:~:text=six%20months), and will defer to such requirements when considered necessary. | ||
|
maelle marked this conversation as resolved.
|
||
|
|
||
| ## Preparing for Submission {#preparing-for-submission} | ||
|
|
||
| ### Asking for help | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
|
|
@@ -31,6 +31,17 @@ Esta guía condensa el proceso de revisión por pares desde el punto de vista de | |||||
| - No debes hacer ningún cambio en tu paquete mientras esté en proceso de revisión, para que todas las personas que lo revisan puedan evaluar el mismo software. ¡No envíes tu paquete hasta que esté en una versión estable! | ||||||
| - Tu paquete seguirá evolucionando después de la revisión, el capítulo sobre *Evolución de paquetes* [proporciona orientación sobre el tema](#evolution). | ||||||
|
|
||||||
| ### Uso de herramientas de IA generativa | ||||||
|
|
||||||
| - El uso de herramientas de IA generativa es aceptable en los paquetes enviados para revisión por pares, tal como se describe en [nuestra publicación inicial en el blog](https://ropensci.org/blog/2026/02/26/ropensci-ai-policy/). | ||||||
| - Tal como se indica en [nuestras políticas generales](#policies-ai), exigimos a todos los autores que envíen trabajos que proporcionen detalles sobre cualquier uso de herramientas de IA generativa en la documentación del paquete, generalmente en los archivos README o en las guías de contribución. | ||||||
|
Member
There was a problem hiding this comment.
Suggested change
|
||||||
| - Las descripciones detalladas sobre el uso de herramientas de IA o las decisiones de diseño también pueden incluirse en documentos separados; en ese caso, deben enlazarse directamente desde el archivo README o la guía de contribución. | ||||||
| - Un ejemplo es [el paquete `HydraR`](https://apaf-bioinformatics.github.io/HydraR/# uso-de-ia-generativa-por-robots), que incluye un enlace en el archivo README principal a los archivos [agents.md](https://apaf-bioinformatics.github.io/HydraR/agents.html) y [DESIGN.md](https://apaf-bioinformatics.github.io/HydraR/DESIGN.html). | ||||||
|
Member
There was a problem hiding this comment.
Suggested change
|
||||||
| - Una regla general muy básica es que, cuanto mayor sea el uso de herramientas de IA generativa en un paquete, más esperaremos que el uso de dichas herramientas esté documentado dentro del propio software. | ||||||
| - Sugerimos utilizar las herramientas de IA de manera que se registren las decisiones que guían los procesos de desarrollo y los resultados dentro del propio software. | ||||||
| - Entre los ejemplos de este tipo de herramientas se encuentran desde [el «spec-kit» de GitHub para el desarrollo basado en especificaciones](https://github.com/github/spec-kit) hasta [nuestra propia herramienta experimental para documentar las decisiones de diseño de software](https://github.com/ropensci-review-tools/designlens). | ||||||
|
Member
There was a problem hiding this comment.
Suggested change
|
||||||
| - Todas ellas comparten el patrón común de generar artefactos adicionales que documentan las decisiones y los procesos de desarrollo junto con el software en sí. | ||||||
|
Member
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| ### Documentación | ||||||
|
|
||||||
| - 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. | ||||||
|
|
||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -31,6 +31,17 @@ Este guia conciso apresenta o processo de revisão de software por pares, para v | |
| - Você não deve fazer nenhuma alteração no seu pacote enquanto ele estiver em análise, para que todas as pessoas revisoras estejam avaliando o mesmo software. Não envie seu pacote até que ele esteja em uma versão estável! | ||
| - Seu pacote continuará a evoluir após a revisão. O capítulo sobre *Evolução do pacote* [fornece mais orientações sobre este tópico](#evolution). | ||
|
|
||
| ### Uso de ferramentas de IA generativa | ||
|
|
||
| - O uso de ferramentas de IA generativa é aceitável em pacotes enviados para revisão por pares, conforme descrito em [nossa postagem inicial no blog](https://ropensci.org/blog/2026/02/26/ropensci-ai-policy/). | ||
| - Conforme estabelecido em [nossas políticas gerais](#policies-ai), exigimos que todos os autores que enviam trabalhos forneçam detalhes sobre qualquer uso de ferramentas de IA generativa na documentação do pacote, geralmente em arquivos README ou em guias de contribuição. | ||
| - Descrições mais detalhadas sobre o uso de ferramentas de IA ou decisões de projeto também podem ser apresentadas em documentos separados; nesse caso, devem ser vinculadas diretamente a partir do arquivo README ou do guia de contribuição. | ||
| - Um exemplo é [o pacote `HydraR`](https://apaf-bioinformatics.github.io/HydraR/# robot-use-of-generative-ai), que fornece um link no README principal para os arquivos [agents.md](https://apaf-bioinformatics.github.io/HydraR/agents.html) e [DESIGN.md](https://apaf-bioinformatics.github.io/HydraR/DESIGN.html). | ||
| - Uma regra geral é que, quanto maior for o uso de ferramentas de IA generativa em um pacote, mais esperaremos que o uso dessas ferramentas seja documentado dentro do próprio software. | ||
| - Sugerimos o uso de ferramentas de IA de forma que as decisões que orientam os processos de desenvolvimento e os resultados sejam registradas dentro do próprio software. | ||
| - Exemplos dessas ferramentas vão desde o [“spec-kit” do GitHub para desenvolvimento orientado por especificações](https://github.com/github/spec-kit) até [nossa própria ferramenta experimental para documentar decisões de projeto de software](https://github.com/ropensci-review-tools/designlens). | ||
| - Todas elas compartilham o padrão comum de produzir artefatos adicionais que documentam as decisões e os processos de desenvolvimento juntamente com o próprio software. | ||
|
|
||
| ### Documentação | ||
|
|
||
| - Para qualquer envio ou consulta de pré-submissão, o README do seu pacote deve fornecer informações suficientes sobre o pacote (objetivos, uso, pacotes semelhantes) para que os editores avaliem seu escopo sem precisar instalar o pacote. Melhor ainda, crie um website pkgdown para permitir uma avaliação mais detalhada da funcionalidade online. | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -261,6 +261,16 @@ The following resources may be helpful for researchers, package authors, editors | |
| - Taylor, J., \& Pagliari, C. (2018). Mining social media data: How are research sponsors and researchers addressing the ethical challenges? Research Ethics, 14(2), 1--39. [https://doi.org/10.1177/1747016117738559](https://doi.org/10.1177/1747016117738559) | ||
| - Zimmer, M. (2010). "But the data is already public": on the ethics of research in Facebook. Ethics and Information Technology, 12(4), 313--325. [https://dx.doi.org/10.1007/s10676-010-9227-5](https://dx.doi.org/10.1007/s10676-010-9227-5) | ||
|
|
||
| ## Use of generative AI tools {#policies-ai} | ||
|
|
||
| Authors must disclose any use of generative AI tools in our submission forms, where we also ask you to, | ||
|
|
||
| > please describe usage, and include links to any relevant aspects of your repository. | ||
|
|
||
| As described in [our initial blog post](https://ropensci.org/blog/2026/02/26/ropensci-ai-policy/), our policies on the use of generative AI tools are expected to develop alongside development in tools themselves, as well as the way their contribute to software development. | ||
| We expect all submitting authors to transparently disclose how generative AI tools may have contributed to any software submitted for peer review. | ||
|
mpadge marked this conversation as resolved.
|
||
| Details are provided in both the [_Guide for Authors_](#authors-guide) and [_Guide for Reviewers_](#reviewerguide). | ||
|
|
||
| ## Code of Conduct {#code-of-conduct} | ||
|
|
||
| rOpenSci's community is our best asset. | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
|
|
@@ -261,6 +261,16 @@ Los siguientes recursos pueden ser útiles para quienes investigan, desarrollan | |||||
| - Taylor, J., y Pagliari, C. (2018).Mining social media data: How are research sponsors and researchers addressing the ethical challenges? Research Ethics, 14(2), 1--39. [https://doi.org/10.1177/1747016117738559](https://doi.org/10.1177/1747016117738559) | ||||||
| - Zimmer, M. (2010). "But the data is already public": on the ethics of research in Facebook. Ethics and Information Technology, 12(4), 313--325. [https://dx.doi.org/10.1007/s10676-010-9227-5](https://dx.doi.org/10.1007/s10676-010-9227-5) | ||||||
|
|
||||||
| ## Uso de herramientas de IA generativa {#policies-ai} | ||||||
|
|
||||||
| Los autores deben declarar cualquier uso de herramientas de IA generativa en nuestros formularios de envío, donde también les pedimos que: | ||||||
|
Member
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| > describan el uso e incluyan enlaces a cualquier aspecto relevante de su repositorio. | ||||||
|
Member
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| Tal como se describe en [nuestra publicación inicial en el blog](https://ropensci.org/blog/2026/02/26/ropensci-ai-policy/), se espera que nuestras políticas sobre el uso de herramientas de IA generativa evolucionen a la par del desarrollo de las propias herramientas, así como de la forma en que estas contribuyen al desarrollo de software. | ||||||
|
Member
There was a problem hiding this comment.
Suggested change
|
||||||
| Esperamos que todos los autores que envíen trabajos revelen de manera transparente cómo las herramientas de IA generativa pueden haber contribuido a cualquier software enviado para revisión por pares. | ||||||
|
Member
There was a problem hiding this comment.
Suggested change
|
||||||
| Los detalles se proporcionan tanto en la [_Guía para autores_](#authors-guide) como en la [_Guía para revisores_](#reviewerguide). | ||||||
|
Member
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| ## Código de conducta {#code-of-conduct} | ||||||
|
|
||||||
| La comunidad de rOpenSci es nuestro mejor recurso. | ||||||
|
|
||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -261,6 +261,16 @@ Os recursos a seguir podem ser úteis para pesquisadores(as), autores(as) de pac | |
| - Taylor, J., \& Pagliari, C. (2018). Mining social media data: How are research sponsors and researchers addressing the ethical challenges? Research Ethics, 14(2), 1--39. [https://doi.org/10.1177/1747016117738559](https://doi.org/10.1177/1747016117738559) | ||
| - Zimmer, M. (2010). "But the data is already public": on the ethics of research in Facebook. Ethics and Information Technology, 12(4), 313--325 [https://dx.doi.org/10.1007/s10676-010-9227-5](https://dx.doi.org/10.1007/s10676-010-9227-5) | ||
|
|
||
| ## Uso de ferramentas de IA generativa {#policies-ai} | ||
|
|
||
| Os autores devem declarar qualquer uso de ferramentas de IA generativa em nossos formulários de submissão, nos quais também solicitamos que: | ||
|
|
||
| > descrevam o uso e incluam links para quaisquer aspectos relevantes do seu repositório. | ||
|
|
||
| Conforme descrito em [nossa postagem inicial no blog](https://ropensci.org/blog/2026/02/26/ropensci-ai-policy/), espera-se que nossas políticas sobre o uso de ferramentas de IA generativa evoluam paralelamente ao desenvolvimento dessas próprias ferramentas, bem como à forma como elas contribuem para o desenvolvimento de software. | ||
| Esperamos que todos os autores que enviam trabalhos divulguem de forma transparente como as ferramentas de IA generativa podem ter contribuído para qualquer software submetido à revisão por pares. | ||
| Os detalhes estão disponíveis tanto no [_Guia para Autores_](#authors-guide) quanto no [_Guia para Revisores_](#reviewerguide). | ||
|
|
||
| ## Código de Conduta {#code-of-conduct} | ||
|
|
||
| A comunidade da rOpenSci é o nosso melhor patrimônio. | ||
|
|
||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.