allcontributors

An alternative implementation in R of the original allcontributors.org to acknowledge all contributors in your ‘README’ (or elsewhere). The original is intended to help acknowledge all contributions including those beyond the contents of an actual repository, such as community or other or less-tangible organisational contributions. This version only acknowledges tangible contributions to a repository, but automates that task to a single function call, in the hope that such simplicity will spur greater usage. In short: This package can’t do everything the original does, but it makes what it does much easier.

Why then?

The original allcontributors.org is primarily a bot which responds to commit messages such as add @user for <contribution>, where <contribution> is one of the recognized types. One advantage of the original system is the diversity of contribution types able to be acknowledged, with each type for a given user appearing as a corresponding emoji below their github avatar as listed on the README. In comparison, this R package:

Works automatically, by calling add_contributors() at any time to add or update contributor acknowledgements.
Works locally without any bot integration
Can add contributors to any file, not just the main README
Offers a variety of formats for listing contributors:
1. divided into sections by types of contributions, or as a single section
2. presented as full grids (like the original), numbered lists of github user names only, or single text strings of comma-separated names.

This ease of automation means you can easily update your contributors list with a simple GitHub workflow, set to update at some regular interval. Your contributor list will then be kept up-to-date without you having to remember or do anything.

Installation

The package is on CRAN, and can be installed with,

install.packages ("allcontributors")

Alternatively, a development version can be installed by enabling the “ropensci” repository from r-universe:

options (repos = c (
    ropensci = "https://ropensci.r-universe.dev",
    CRAN = "https://cloud.r-project.org"
))

The install.packages() command will then install the development version. Alternatively, any of the following options may be used for those who prefer not to use GitHub:

# install.packages("remotes")
remotes::install_git ("https://git.sr.ht/~ropensci/allcontributors")
remotes::install_git ("https://codeberg.org/mpadge/allcontributors")
remotes::install_bitbucket ("mpadge/allcontributors")
remotes::install_gitlab ("mpadge/allcontributors")
remotes::install_github ("mpadge/allcontributors")

The package can then be loaded the usual way:

library (allcontributors)

Usage

The primary function of the package, add_contributors(), adds a table of all contributors by default to the main README.md file (and README.Rmd if that exists). Tables or lists can be added to other files by specifying the files argument of that function. The appearance of the contributors table is determined by several parameters in that function, including:

type For the type of contributions to include (code, contributors who open issues, contributors who discuss issues).
num_sections For whether to present contributors in 1, 2, or 3 distinct sections, dependent upon which types of contributions are to be acknowledged.
format Determining whether contributors are presented in a grid with associated avatars of each contributor, as in the original, an enumerated list of github user names only, or a single text string of comma-separated names.

Contribution data are obtained by querying the github API, for which a local key should be set as an environmental variable containing the name "GITHUB" (either via Sys.setenv(), or as an equivalent entry in a file ~/.Renviron).

If the main README file(s) contains a markdown section entitled "Contributors", the add_contributors() function will add a table of contributors there, otherwise it will be appended to the end of the document(s). If you wish your contributors table to be somewhere other than at the end of the README file(s), start by adding an empty "## Contributors section to the file(s) and the function will insert the table at that point.

Any time you wish to update your contributor list, simply re-run the add_contributors() function. There’s even an open_issue parameter that will automatically open or update a github issue on your repository so that contributors will be pinged about them being added to your list of contributors.

The data used to construct the contributions table can also be extracted without writing to the README file(s) with the function get_contributors():

get_contributors (org = "ropensci", repo = "allcontributors")

#> ✔  Extracted code contributors
#> ✔  Extracted github issue contributors
#> ✔  Downloaded GitHub URLs
#>       logins contributions
#> 1     mpadge           176
#> 2     maelle            NA
#> 3 shamindras            NA
#> 4 assignUser            NA
#>                                                                                            avatar
#> 1                                             https://avatars.githubusercontent.com/u/6697851?v=4
#> 2  https://avatars.githubusercontent.com/u/8360597?u=824f03caa87c92420352e3dd9a05470320a67412&v=4
#> 3  https://avatars.githubusercontent.com/u/7627188?u=d05fb551796e6ce6db64ae43cd8ce48a0217ef85&v=4
#> 4 https://avatars.githubusercontent.com/u/16141871?u=bbf2ca4641e8ec034a9cdb583e62e3a94c372824&v=4
#>            type
#> 1          code
#> 2 issue_authors
#> 3 issue_authors
#> 4 issue_authors

Keeping your allcontributors Acknowledgements up-to-date

The “Contributors” sections of files can be updated at any time by calling calling add_contributors(). If your contributors have not changed then your lists of 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 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 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:

release_bullets <- function () {
    "Run `allcontributors::add_contributors()`"
}

The function does not need to be exported, and should return a single text item (which you can modify to suit your own needs). That function will then be read by usethis and the text within it automatically added to the checklist items created on calling the usethis::use_release_issue() function.

Forcing updates

The add_contributors() 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. 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() again.

More Information

The package has a single vignette which visually demonstrates the various formats in which an “allcontributors” section can be presented.

Code of Conduct

Please note that this package is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.

Contributors

All contributions to this project are gratefully acknowledged using the allcontributors package following the allcontributors specification. Contributions of any kind are welcome!