From 79c090d625076cf8c613aa24889698f6aef249fa Mon Sep 17 00:00:00 2001 From: mpadge Date: Mon, 18 Nov 2024 16:28:52 +0100 Subject: [PATCH] update readme to close #15 --- DESCRIPTION | 2 +- NEWS.md | 8 ++++++++ README.Rmd | 50 ++++++++++++++++++++++++++++++++++++++++++-------- README.md | 50 +++++++++++++++++++++++++++++++++++++++++--------- codemeta.json | 2 +- 5 files changed, 93 insertions(+), 19 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index fbbb3f1..9277e35 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: allcontributors Title: Acknowledge all Contributors to a Project -Version: 0.2.2.007 +Version: 0.2.2.008 Authors@R: c( person("Mark", "Padgham", , "mark.padgham@email.com", role = c("aut", "cre")), person("Chris", "Hartgerink", role = "aut"), diff --git a/NEWS.md b/NEWS.md index 2908ca7..8d228f5 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,5 +1,13 @@ # v0.2.2.00X (Current development version) +## Major changes + +- Added a [GitHub workflow](https://github.com/ropensci/allcontributors/blob/main/.github/workflows/allcontributors.yml) to automatically run `add_contributors()` + +## Minor changes + +- Updated documentation to described different ways of keeping allcontributors lists up-to-date (#15; thanks to @maelle) + --- # v0.2.2 diff --git a/README.Rmd b/README.Rmd index 04d7453..5d4e96f 100644 --- a/README.Rmd +++ b/README.Rmd @@ -177,13 +177,49 @@ print (dat) ``` -## Updating Contributor Acknowledgements +## Keeping your allcontributors Acknowledgements up-to-date -"Contributors" sections of files will be automatically updated to reflect any new -contributions by simply calling +The "Contributors" sections of files can be updated at any time by calling +calling [`add_contributors()`](https://docs.ropensci.org/allcontributors/reference/add_contributors.html). If your contributors have not changed then your lists of acknowledgements will -not be changed. The +not be changed. The most direct way to update your allcontributors list is to +remember to manually call that function. + +### A GitHub Workflow + +This package also includes a [GitHub workflow +file](https://github.com/ropensci/allcontributors/blob/main/.github/workflows/allcontributors.yml) +which you can simply copy and add to your own repository. Once pushed with your +repository, this workflow will be automatically run at the default monthly +interval (or whatever value you interval you wish to change that to), your +README file updated, and the result committed to your repository. Your +allcontributors list will then be automatically updated without you having to +do anything. + +### A `usethis::use_release_issue()` check item + +Many people use the [`usethis::use_release_issue()` +function](https://usethis.r-lib.org/reference/use_release_issue.html) to +automatically open an issue on GitHub containing a checklist to help prepare +for package releases. You can easily add an additional checklist item to this +list by including the following function somewhere in your package code: + +```{r} +release_bullets <- function () { + "Run `allcontributors::add_contributors()`" +} +``` + +The function should return a single text item (which you can modify to suit +your own needs), and that will be automatically added to the checklist item +created on calling the [`usethis::use_release_issue()` +function](https://usethis.r-lib.org/reference/use_release_issue.html). + + +### Forcing updates + +The [`add_contributors()`](https://docs.ropensci.org/allcontributors/reference/add_contributors.html) function has an additional parameter which may be set to `force_update = TRUE` to force lists to be updated regardless of whether contributions have changed. @@ -191,10 +227,8 @@ This can be used to change the formats of acknowledgements at any time. If anything goes wrong, the easiest way to replace a contributions section is to simply delete the old ones from all files, and call [`add_contributors()`](https://docs.ropensci.org/allcontributors/reference/add_contributors.html) -again. This package also includes a [GitHub workflow -file](https://github.com/ropensci/allcontributors/blob/main/.github/workflows/allcontributors.yml) -which you can simply copy and add to your own repository, and your -"allcontributors" section will be automatically updated at regular intervals. +again. + ## More Information diff --git a/README.md b/README.md index 1aec8bd..ce1c0fb 100644 --- a/README.md +++ b/README.md @@ -158,13 +158,49 @@ get_contributors (org = "ropensci", repo = "allcontributors") #> 3 issue_authors #> 4 issue_authors -## Updating Contributor Acknowledgements +## Keeping your allcontributors Acknowledgements up-to-date -“Contributors” sections of files will be automatically updated to -reflect any new contributions by simply calling +The “Contributors” sections of files can be updated at any time by +calling calling [`add_contributors()`](https://docs.ropensci.org/allcontributors/reference/add_contributors.html). If your contributors have not changed then your lists of -acknowledgements will not be changed. The +acknowledgements will not be changed. The most direct way to update your +allcontributors list is to remember to manually call that function. + +### A GitHub Workflow + +This package also includes a [GitHub workflow +file](https://github.com/ropensci/allcontributors/blob/main/.github/workflows/allcontributors.yml) +which you can simply copy and add to your own repository. Once pushed +with your repository, this workflow will be automatically run at the +default monthly interval (or whatever value you interval you wish to +change that to), your README file updated, and the result committed to +your repository. Your allcontributors list will then be automatically +updated without you having to do anything. + +### A `usethis::use_release_issue()` check item + +Many people use the [`usethis::use_release_issue()` +function](https://usethis.r-lib.org/reference/use_release_issue.html) to +automatically open an issue on GitHub containing a checklist to help +prepare for package releases. You can easily add an additional checklist +item to this list by including the following function somewhere in your +package code: + +``` r +release_bullets <- function () { + "Run `allcontributors::add_contributors()`" +} +``` + +The function should return a single text item (which you can modify to +suit your own needs), and that will be automatically added to the +checklist item created on calling the [`usethis::use_release_issue()` +function](https://usethis.r-lib.org/reference/use_release_issue.html). + +### Forcing updates + +The [`add_contributors()`](https://docs.ropensci.org/allcontributors/reference/add_contributors.html) function has an additional parameter which may be set to `force_update = TRUE` to force lists to be updated regardless of whether @@ -173,11 +209,7 @@ acknowledgements at any time. If anything goes wrong, the easiest way to replace a contributions section is to simply delete the old ones from all files, and call [`add_contributors()`](https://docs.ropensci.org/allcontributors/reference/add_contributors.html) -again. This package also includes a [GitHub workflow -file](https://github.com/ropensci/allcontributors/blob/main/.github/workflows/allcontributors.yml) -which you can simply copy and add to your own repository, and your -“allcontributors” section will be automatically updated at regular -intervals. +again. ## More Information diff --git a/codemeta.json b/codemeta.json index 5d8f32a..0756785 100644 --- a/codemeta.json +++ b/codemeta.json @@ -7,7 +7,7 @@ "codeRepository": "https://github.com/ropensci/allcontributors", "issueTracker": "https://github.com/ropensci/allcontributors/issues", "license": "https://spdx.org/licenses/GPL-3.0", - "version": "0.2.2.007", + "version": "0.2.2.008", "programmingLanguage": { "@type": "ComputerLanguage", "name": "R",