An alternative implementation in R of the originalall-contributors to acknowledge all contributors in your ‘README’ (or elsewhere). The original is intended to help acknowledgeall 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 originalall-contributors is primarily a bot which responds to commit messages such asadd @user for <contribution>, where<contribution> is one of therecognized types. As said above, the relative advantage of that original system lies primarily in the diversity of contribution types able to be acknowledged, with each type for a given user appearing as a correspondingemoji 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:
- divided into sections by types of contributions, or as a single section
- presented as full grids (likethe original), numbered lists of github user names only, or single text strings of comma-separated names.
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 fromr-universe:
Theinstall.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:
Usage
The primary function of the package,add_contributors(), adds a table of all contributors by default to the mainREADME.md file (andREADME.Rmd if that exists). Tables or lists can be added to other files by specifying thefiles argument of that function. The appearance of the contributors table is determined by several parameters in that function, including:
typeFor the type of contributions to include (code, contributors who open issues, contributors who discuss issues).num_sectionsFor whether to present contributors in 1, 2, or 3 distinct sections, dependent upon whichtypes of contributions are to be acknowledged.formatDetermining whether contributors are presented in a grid with associated avatars of each contributor, as inthe 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 viaSys.setenv(), or as an equivalent entry in a file~/.Renviron).
If the mainREADME file(s) contains a markdown section entitled"Contributors", theadd_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 theREADME 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 theadd_contributors() function. There’s even anopen_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 theREADME file(s) with the functionget_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_authorsUpdating Contributor Acknowledgements
“Contributors” sections of files will be automatically updated to reflect any new contributions by simply callingadd_contributors(). If your contributors have not changed then your lists of acknowledgements will not be changed. Theadd_contributors() function has an additional parameter which may be set toforce_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 calladd_contributors() again.
More Information
The package has asingle 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 aContributor 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 theallcontributors package following theallcontributors specification. Contributions of any kind are welcome!