From 98dfa05fec039da79f280b0aaa8fbd35dde31283 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ma=C3=ABlle=20Salmon?= Date: Thu, 28 Sep 2023 08:23:58 +0200 Subject: [PATCH] add placeholders --- maintenance_cheatsheet.pt.Rmd | 50 ++++++++++ maintenance_collaboration.pt.Rmd | 165 +++++++++++++++++++++++++++++++ 2 files changed, 215 insertions(+) create mode 100644 maintenance_cheatsheet.pt.Rmd create mode 100644 maintenance_collaboration.pt.Rmd diff --git a/maintenance_cheatsheet.pt.Rmd b/maintenance_cheatsheet.pt.Rmd new file mode 100644 index 000000000..9eb2bba61 --- /dev/null +++ b/maintenance_cheatsheet.pt.Rmd @@ -0,0 +1,50 @@ +# rOpenSci package maintenance cheatsheet {#maintainer-cheatsheet} + +```{block, type="summaryblock"} +A reminder of infrastructure and contact channels for maintainers of rOpenSci packages. + +``` + +## Help needed? {#help-needed} + +If you need punctual help (say, a PR review; or some CI troubleshooting), or help looking for co-maintainers or a new maintainer, or if you need us to retire your package, ping us in GitHub via `@ropensci/admin` or email `info@ropensci.org`. +You can also use our slack package maintenance channel. + +Never hesitate to ask for help. + +## GitHub repository access {#git-hub-repository-access} + +You should have administrative access to your package's GitHub repository. +If that is no longer the case (say, the automated process failed; or you lost access after having to temporarily deactivate two-factor authentication), +please contact us via `info@ropensci.org`. + +## Other GitHub topics {#other-git-hub-topics} + +If you have any GitHub question or request (adding a collaborator to the GitHub organization for instance) you can use a public channel of the rOpenSci slack workspace or ping `@ropensci/admin` on GitHub. + +## pkgdown documentation {#pkgdown-documentation} + +See [rOpenSci docs](#rodocsci). + +## Access to rOpenSci slack workspace {#access-to-ropensci-slack-workspace} + +Package maintainers and developers should get access to [rOpenSci slack](https://contributing.ropensci.org/resources.html#channels). +If you did not get the invitation or did not accept it in time, +or if you want a new regular contributor receive an invitation please email `info@ropensci.org`, +indicating to which email address you wish to receive the invitation. + +You might find the #package-maintenance channel relevant for Q\&A as well as friendly commiseration when needed. + +## Package blog posts {#package-blog-posts} + +Refer to our [blog guide](https://blogguide.ropensci.org/). + +## Package issues promotion {#package-issues-promotion} + +Label issues with "help wanted" to get them [broadcasted to the community](https://ropensci.org/help-wanted/). + +## Package use cases promotion {#package-use-cases-promotion} + +You can report use cases of your package or encourage users to report them via our forum to get them [published on our website](https://ropensci.org/usecases/) and in our newsletter. + + diff --git a/maintenance_collaboration.pt.Rmd b/maintenance_collaboration.pt.Rmd new file mode 100644 index 000000000..05eac3813 --- /dev/null +++ b/maintenance_collaboration.pt.Rmd @@ -0,0 +1,165 @@ +--- +aliases: + - collaboration.html +--- + +# Collaboration Guide {#collaboration} + +```{block, type="summaryblock"} +Having contributors will improve your package, and if you onboard some of them as package authors with [write permissions to the repo](https://help.github.com/articles/repository-permission-levels-for-an-organization/), your package will be more sustainably developed. +It can also be very enjoyable to work as a team! + +This chapter contains our guidance for collaboration, in a [section about making your repo contribution- and collaboration-friendly](#friendlyfiles) by infrastructure (code of conduct, contribution guidelines, issue labels); and [ a section about how to collaborate with new contributors](#workingcollaborators), in particular in the context of the rOpenSci's "ropensci" GitHub organization. + +Besides these mostly technical tips, it is important to remember to be kind, and to take others' perspective into account especially when their priorities differ from yours. +``` + +## Make your repo contribution and collaboration friendly {#friendlyfiles} + +### Code of conduct {#coc-file} + +After transfer to our GitHub organization, [rOpenSci Code of Conduct](https://ropensci.org/code-of-conduct/) will apply to your project. +Please add this text to the README + +```markdown +Please note that this package is released with a [Contributor +Code of Conduct](https://ropensci.org/code-of-conduct/). +By +contributing to this project, you agree to abide by its terms. +``` + +And delete the package current code of conduct if there was one. + +### Contributing guide {#contributing-guide} + +You can use issue, pull request and contributing guidelines. +Having a contributing file as `.github/CONTRIBUTING.md` or `docs/CONTRIBUTING.md` is compulsory. +An easy way to insert a template for a contributing guide is the [`use_tidy_contributing()` function from the `usethis` package](https://usethis.r-lib.org/reference/tidyverse.html), which inserts [this template](https://github.com/r-lib/usethis/blob/main/inst/templates/tidy-contributing.md) as `.github/CONTRIBUTING.md`. +A more extensive example is [this template by Peter Desmet](https://gist.github.com/peterdesmet/e90a1b0dc17af6c12daf6e8b2f044e7c), or the comprehensive [GitHub wiki pages for the mlr3 package](https://github.com/mlr-org/mlr3/wiki). +These and other templates will generally need to be modified for use with an rOpenSci package, particularly by referring and linking to our [Code of Conduct](https://ropensci.org/code-of-conduct/), as described elsewhere [in this book](#code-of-conduct). +Modifying a generic contributing guide to add a personal touch also tends to make it look less generic and more sincere. +Personal preferences in a contributing guide include: + +- Style preferences? You might however prefer to make style a configuration (of [lintr](https://github.com/jimhester/lintr), [styler](https://styler.r-lib.org/)) or to [fix code style yourself](https://github.com/rstudio/blogdown/pull/432#pullrequestreview-368391904) especially if you don't use a popular code style like the [tidyverse coding style](https://style.tidyverse.org/). + +- Infrastructure like roxygen2? + +- Workflow preferences? Issue before a PR? + +- A scope statement, like [in the skimr package](https://github.com/ropensci/skimr/blob/main/.github/CONTRIBUTING.md#understanding-the-scope-of-skimr)? + +- Sandbox account creation? Mocking in tests? Linking to external docs? + +rOpenSci further encourages contributing guides to include a lifecycle statement clarifying visions and expectations for the future development of your package, like [in this example](https://github.com/ecohealthalliance/fasterize/blob/master/CONTRIBUTING.md#roadmap). +Statistical packages are required to have a lifecycle statement, as specified in [*General Statistical Stanards* G1.2](https://stats-devguide.ropensci.org/standards.html#documentation). +That links provides a template for a simple lifecycle statement. +CONTRIBUTING.md files can also describe how you acknowledge contributions (see [this section](#attributions)). + +We encourage you to direct feedback that is not a bug report or a feature request to [rOpenSci forum](https://discuss.ropensci.org/), after making sure you'd see such questions on the forum. Users can use the forum to ask questions about use and report their use cases, and you can subscribe to individual categories and tags to receive notifications about your package. Feel free to mention this in the docs of your package and/or the contributing guidelines/issue template. Please direct your users to tag posts with the package name. + +Once a pull request is closer to being merged, you could use [a GitHub Actions PR workflow to style the code with styler](https://github.com/r-lib/actions/blob/master/examples/pr-commands.yaml). + +### Issue management {#issue-management} + +By using GitHub features around issues you can help potential contributors find them, and make your roadmap public. + +#### Issue templates {#issue-templates} + +You could use one or several [issue template(s)](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository#creating-issue-templates=) to help users fill better bug reports or feature requests. +When there are several issue templates, users who click on opening a new issue see a menu that guide their choices. + +You can even [configure one of the choices](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=) to point to somewhere outside of your repository (for instance a discussion forum). + +Refer to [GitHub docs](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository). + +#### Issue labelling {#issue-labelling} + +You can use labels such as "help wanted" and "good first issue" to help potential collaborators, including newbies, find your repo. [Cf GitHub article](https://help.github.com/articles/helping-new-contributors-find-your-project-with-labels/). You can also use the "Beginner" label. See [examples of beginner issues over all ropensci repos](https://github.com/search?q=user%3Aropensci+user%3Aropenscilabs+label%3ABeginner+state%3Aopen&type=Issues). + +#### Pinning issues {#pinning-issues} + +You can [pin up to 3 issues by repository](https://docs.github.com/en/articles/pinning-an-issue-to-your-repository) that will then appear at the top of your issue tracker as nice issue cards. +It can help advertise what your priorities are. + +#### Milestones {#milestones} + +You can [create milestones](https://docs.github.com/en/issues/using-labels-and-milestones-to-track-work/about-milestones) and assign issues to them, which help see what you plan for the next version of your package for instance. + +### Communication with users {#communication-with-users} + +You can point users to rOpenSci forum if you monitor it, or enable [GitHub Discussions](https://docs.github.com/en/discussions) for your package repository. +Each GitHub discussion can be converted to an issue if needed (and the other way round, issues can be converted to discussions). + +## Working with collaborators {#workingcollaborators} + +First thing first: keep in touch with your GitHub repository! + +- do not forget to [**watch your GitHub repository**](https://docs.github.com/en/github/managing-subscriptions-and-notifications-on-github/managing-subscriptions-for-activity-on-github) to be notified of issues or pull requests (alternatively, if you work in bursts, maybe add the information to the contributing guide). + +- do not forget to push updates you have locally. + +- disable failing tests if you cannot fix them as they create noise in PRs that can puzzle new contributors. + +### Onboarding collaborators {#onboarding-collaborators} + +There's no general rOpenSci rule as to how you should onboard collaborators. You should increase their rights to the repo as you gain trust, and you should definitely acknowledge contributions (see [this section](#attributions)). + +You can ask a new collaborator to make PRs (see following section for assessing a PR locally, i.e. beyond CI checks) to dev/main and assess them before merging, and after a while let them push to main, although you might want to keep a system of PR reviews... even for yourself once you have team mates! + +A possible model for onboarding collaborators is provided by Jim Hester in [his `lintr` repo](https://github.com/jimhester/lintr/issues/318). + +If your problem is *recruiting* collaborators, you can post an open call like Jim Hester's [on Twitter](https://twitter.com/jimhester_/status/997109466674819074), [GitHub](https://github.com/jimhester/lintr/issues/318), and as an rOpenSci package author, you can ask for help in rOpenSci slack and ask rOpenSci team for ideas for recruiting new collaborators. + +### Working with collaborators (including yourself) {#git-workflow} + +[Branches](https://happygitwithr.com/git-branches.html) are cheap. Use them extensively when developing features, testing out new ideas, fixing problems. + +One of the branches is the default / main branch, where, if you follow [trunk-based development](https://www.atlassian.com/continuous-delivery/continuous-integration/trunk-based-development), you "merge small, frequent updates". +See also [GitHub flow](https://docs.github.com/en/get-started/quickstart/github-flow) and [GitLab flow](https://docs.gitlab.com/ee/topics/gitlab_flow.html) docs. +You might want to frequently increment version numbers (in `DESCRIPTION`). +One particular aspect of working with collaborators is reviewing pull requests, with some useful guidance in: + +- [The Art of Giving and Receiving Code Reviews (Gracefully), by Alex Hill](https://www.alexandra-hill.com/2018/06/25/the-art-of-giving-and-receiving-code-reviews/); +- [GitHub documentation about PR reviews](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews). + +You might want to tinker with your GitHub repository settings to, for instance, [require pull request reviews before merging](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/about-protected-branches#require-pull-request-reviews-before-merging=). +See also GitHub docs about ["code owners"](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners). + +For making and reviewing pull requests we recommend [exploring usethis functions](https://usethis.r-lib.org/articles/pr-functions.html). + +For your "git remote" setup refer to [happy git with r](https://happygitwithr.com/common-remote-setups.html). +See also [Useful Git patterns for real life](https://happygitwithr.com/workflows-intro.html) in the same book. + +### Be generous with attributions {#attributions} + +If someone contributes to your repository consider adding them in DESCRIPTION, as contributor ("ctb") for small contributions, author ("aut") for bigger contributions. Traditionally when citing a package in a scientific publication only "aut" authors are listed, not "ctb" contributors; and on `pkgdown` websites only "aut" names are listed on the homepage, all authors being listed on the authors/ page. + +At a minimum consider adding the name of contributors near the feature/bug fix line in [NEWS.md](#news). + +We recommend your being generous with such acknowledgements, because it is a nice thing to do and because it will make folks more likely to contribute again to your package or other repos of the organization. + +As a reminder from [our packaging guidelines](#building) if your package was reviewed and you feel that your reviewers have made a substantial contribution to the development of your package, you may list them in the `Authors@R` field with a Reviewer contributor type (`"rev"`), like so: + +``` + person("Bea", "Hernández", role = "rev", + comment = "Bea reviewed the package (v. X.X.XX) for rOpenSci, see "), +``` + +Only include reviewers after asking for their consent. Read more in [this blog post "Thanking Your Reviewers: Gratitude through Semantic Metadata"](https://ropensci.org/blog/2018/03/16/thanking-reviewers-in-metadata/). Note that 'rev' will raise a CRAN NOTE unless the package is built using R v3.5. Make sure you use `roxygen2`'s latest CRAN version. + +Please do not list editors as contributors. Your participation in and contribution to rOpenSci is thanks enough! + +### Welcoming collaborators to rOpenSci {#welcoming-collaborators-to-ropensci} + +If you give someone write permissions to the repository, + +- please contact a [staff member](https://ropensci.org/about#team) so that this new contributor might get **invited to rOpenSci's "ropensci" GitHub organization** (instead of being [an outside collaborator](https://help.github.com/articles/repository-permission-levels-for-an-organization/#outside-collaborators)) + +- please contact rOpenSci's [community manager or another staff member](https://ropensci.org/about#team) so that this new contributor might get get **invited to rOpenSci Slack workspace**. + +## Further resources {#further-resources} + +- rOpenSci community call [Set Up Your Package to Foster a Community](https://ropensci.org/commcalls/apr2021-pkg-community/). +- For re-using kind and usual answers, consider GitHub's [saved replies](https://docs.github.com/en/github/writing-on-github/working-with-saved-replies/using-saved-replies). + +