diff --git a/DESCRIPTION b/DESCRIPTION index 475ad46..c91aad7 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -16,6 +16,10 @@ Imports: jsonlite, stringr, withr +Suggests: + spelling Encoding: UTF-8 +Language: en-GB LazyData: true RoxygenNote: 7.3.1 +Roxygen: list(markdown = TRUE) diff --git a/NAMESPACE b/NAMESPACE index 92992e5..ea0d7f5 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -2,10 +2,10 @@ export(add_badge_codefactor) export(add_badge_status) +export(add_badge_zenodo) export(add_contributing) export(add_issue_template) export(add_logo) -export(add_zenodo_badge) importFrom(jsonlite,fromJSON) importFrom(stringr,str_detect) importFrom(stringr,str_replace_all) diff --git a/R/add_badge.R b/R/add_badge.R index 6c5e7fd..b768679 100644 --- a/R/add_badge.R +++ b/R/add_badge.R @@ -151,7 +151,7 @@ add_badge_codefactor <- function(repo = NULL, #' @export #' -add_zenodo_badge <- function(repo = NULL, +add_badge_zenodo <- function(repo = NULL, path = NULL) { ## Determine repo ---- if (is.null(repo)) diff --git a/README.Rmd b/README.Rmd index 0e5d7ed..3de8312 100644 --- a/README.Rmd +++ b/README.Rmd @@ -31,13 +31,11 @@ Currently, `pakete` includes functions for: 1. creating GitHub checklists for tasks in the package submission process; -2. creating `_pkgdown.yml` templates for projects that I work on; +2. creating `CONTRIBUTING.md` file; -3. creating line snippets for `DESCRIPTION` file; +3. adding `repostatus` badge; and, -4. creating `CONTRIBUTING.md` file; - -5. adding `repostatus` badge; +4. adding Zenodo DOI badge. ## Installation @@ -52,6 +50,52 @@ install.packages( ## Usage +### Creating GitHub issues checklist template for CRAN submissions + +It is useful for some to have a checklist of tasks to be done as part of the CRAN submission process. The [*Releasing to CRAN* chapter](https://r-pkgs.org/release.html) of second edition of the R packages book provides good templates for tasks to do for an [initial CRAN release](https://r-pkgs.org/release.html#sec-release-initial), an [update CRAN release](https://r-pkgs.org/release.html#keeping-up-with-change), a [submission of package to CRAN](https://r-pkgs.org/release.html#sec-release-process), and a [post-acceptance to CRAN](https://r-pkgs.org/release.html#sec-release-post-acceptance). + +The function `add_issue_template()` assists in creating a GitHub issue template for your package repository for each of these stages of preparing for, submitting to, and getting accepted by CRAN. So, if you want to setup an issues checklist that you can use for preparing to submit to CRAN for an initial release, use: + +```{r issue-template, eval = FALSE} +library(pakete) + +add_issue_template("initial-cran-release") +``` + +This will create a markdown file called `initial-cran-release.md` inside the `.github/ISSUE_TEMPLATE` directory (this will be created if it doesn't exist yet) which is where GitHub looks for issue templates to use. + +Then, once you commit and push this to your GitHub remote repository and merge it to your `main` branch, you will now see a choice of **Initial CRAN release** to use as a template whenever you open a new issue. + +### Creating a CONTRIBUTING.md file + +If you need help with getting specific language for a `CONTRIBUTING.md` document in your repository, you may want to consider using the template available from this package as follows: + +```{r contributing-file, eval = FALSE} +add_contributing(repo = "YOUR_GITHUB_USERNAME/YOUR_REPO_NAME") +``` + +This will create a `CONTRIBUTING.md` file within the `.github` directory (this will be created if it doesn't exist). Do note that the contributing process described in this markdown document is the preferred process of those who developed the `pakete` package. If you are starting out and need something to use or somethign to build on, then this can help. + +### Adding a `repostatus` badge + +If you would like to add one of the badges from [`repostatus`](https://www.repostatus.org/) to signify the development status of your project, you can do so as follows: + +```{r repostatus-badge, eval = FALSE} +add_badge_status("wip") +``` + +This will add a status badge to your README file in the block where badges are usually placed. + +### Adding a Zenodo badge + +If you use Zenodo and would like to add a Zenodo badge to your README (even if you haven't made a release for your repository/project), you can use the `add_badge_zenodo()` function as follows: + +```{r zenodo-badge, eval = FALSE} +add_badge_zenodo(repo = "YOUR_GITHUB_USERNAME/YOUR_REPO_NAME") +``` + +This will add a Zenodo badge to your README file in the block were badges are usually placed. Please note that whilst this can be used to add a Zenodo badge even if you haven't made a GitHub release yet, the actual badge will only appear and the DOI assigned to your repository will only be issued once you have made your first GitHub release. Hence, you should only do this either as a post-acceptance to CRAN step when you will make your first GitHub release after your CRAN release or as part of a GitHub pre-release to activate a DOI for your repository. It would not be advisable to add this badge to your README without a GitHub release before you submit to CRAN as you will have check errors in relation to the Zenodo release URL. + ## Citation If you find the `pakete` package useful please cite using the suggested citation provided by a call to the `citation()` function as follows: @@ -64,5 +108,5 @@ citation("pakete") Feedback, bug reports and feature requests are welcome; file issues or seek support [here](https://github.com/katilingban/pakete/issues). If you would like to contribute to the package, please see our [contributing guidelines](https://katilingban.io/pakete/CONTRIBUTING.html). -Please note that the `paketa` project is released with a [Contributor Code of Conduct](https://katilingban.io/pakete/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms. +Please note that the `pakete` project is released with a [Contributor Code of Conduct](https://katilingban.io/pakete/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms. diff --git a/README.md b/README.md index ce838e2..c6f819c 100644 --- a/README.md +++ b/README.md @@ -27,13 +27,11 @@ Currently, `pakete` includes functions for: 1. creating GitHub checklists for tasks in the package submission process; -2. creating `_pkgdown.yml` templates for projects that I work on; +2. creating `CONTRIBUTING.md` file; -3. creating line snippets for `DESCRIPTION` file; +3. adding `repostatus` badge; and, -4. creating `CONTRIBUTING.md` file; - -5. adding `repostatus` badge; +4. adding Zenodo DOI badge. ## Installation @@ -49,6 +47,93 @@ install.packages( ## Usage +### Creating GitHub issues checklist template for CRAN submissions + +It is useful for some to have a checklist of tasks to be done as part of +the CRAN submission process. The [*Releasing to CRAN* +chapter](https://r-pkgs.org/release.html) of second edition of the R +packages book provides good templates for tasks to do for an [initial +CRAN release](https://r-pkgs.org/release.html#sec-release-initial), an +[update CRAN +release](https://r-pkgs.org/release.html#keeping-up-with-change), a +[submission of package to +CRAN](https://r-pkgs.org/release.html#sec-release-process), and a +[post-acceptance to +CRAN](https://r-pkgs.org/release.html#sec-release-post-acceptance). + +The function `add_issue_template()` assists in creating a GitHub issue +template for your package repository for each of these stages of +preparing for, submitting to, and getting accepted by CRAN. So, if you +want to setup an issues checklist that you can use for preparing to +submit to CRAN for an initial release, use: + +``` r +library(pakete) + +add_issue_template("initial-cran-release") +``` + +This will create a markdown file called `initial-cran-release.md` inside +the `.github/ISSUE_TEMPLATE` directory (this will be created if it +doesn’t exist yet) which is where GitHub looks for issue templates to +use. + +Then, once you commit and push this to your GitHub remote repository and +merge it to your `main` branch, you will now see a choice of **Initial +CRAN release** to use as a template whenever you open a new issue. + +### Creating a CONTRIBUTING.md file + +If you need help with getting specific language for a `CONTRIBUTING.md` +document in your repository, you may want to consider using the template +available from this package as follows: + +``` r +add_contributing(repo = "YOUR_GITHUB_USERNAME/YOUR_REPO_NAME") +``` + +This will create a `CONTRIBUTING.md` file within the `.github` directory +(this will be created if it doesn’t exist). Do note that the +contributing process described in this markdown document is the +preferred process of those who developed the `pakete` package. If you +are starting out and need something to use or somethign to build on, +then this can help. + +### Adding a `repostatus` badge + +If you would like to add one of the badges from +[`repostatus`](https://www.repostatus.org/) to signify the development +status of your project, you can do so as follows: + +``` r +add_badge_status("wip") +``` + +This will add a status badge to your README file in the block where +badges are usually placed. + +### Adding a Zenodo badge + +If you use Zenodo and would like to add a Zenodo badge to your README +(even if you haven’t made a release for your repository/project), you +can use the `add_badge_zenodo()` function as follows: + +``` r +add_badge_zenodo(repo = "YOUR_GITHUB_USERNAME/YOUR_REPO_NAME") +``` + +This will add a Zenodo badge to your README file in the block were +badges are usually placed. Please note that whilst this can be used to +add a Zenodo badge even if you haven’t made a GitHub release yet, the +actual badge will only appear and the DOI assigned to your repository +will only be issued once you have made your first GitHub release. Hence, +you should only do this either as a post-acceptance to CRAN step when +you will make your first GitHub release after your CRAN release or as +part of a GitHub pre-release to activate a DOI for your repository. It +would not be advisable to add this badge to your README without a GitHub +release before you submit to CRAN as you will have check errors in +relation to the Zenodo release URL. + ## Citation If you find the `pakete` package useful please cite using the suggested @@ -80,6 +165,6 @@ you would like to contribute to the package, please see our [contributing guidelines](https://katilingban.io/pakete/CONTRIBUTING.html). -Please note that the `paketa` project is released with a [Contributor +Please note that the `pakete` project is released with a [Contributor Code of Conduct](https://katilingban.io/pakete/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms. diff --git a/man/add_badge.Rd b/man/add_badge.Rd index ef90222..e13b89c 100644 --- a/man/add_badge.Rd +++ b/man/add_badge.Rd @@ -3,7 +3,7 @@ \name{add_badge_status} \alias{add_badge_status} \alias{add_badge_codefactor} -\alias{add_zenodo_badge} +\alias{add_badge_zenodo} \title{Add badges to README} \usage{ add_badge_status( @@ -15,18 +15,18 @@ add_badge_status( add_badge_codefactor(repo = NULL, path = NULL) -add_zenodo_badge(repo = NULL, path = NULL) +add_badge_zenodo(repo = NULL, path = NULL) } \arguments{ \item{status}{A character value for status to be assigned to project. This -can be either *"concept"*, *"wip"*, *"suspended"*, *"abandoned"*, -*"active"*, *"inactive"*, *"unsupported"*, or *"moved"*.} +can be either \emph{"concept"}, \emph{"wip"}, \emph{"suspended"}, \emph{"abandoned"}, +\emph{"active"}, \emph{"inactive"}, \emph{"unsupported"}, or \emph{"moved"}.} \item{path}{Path to file to add repostatus badge to. Set to NULL by default which would indicate that a README file in the root directory of the project is the target file.} -\item{.url}{If `status` is "moved", the URL to which the repository has moved +\item{.url}{If \code{status} is "moved", the URL to which the repository has moved to. Otherwise NULL.} \item{repo}{Short remote git repository name. If NULL, is determined based @@ -34,7 +34,7 @@ on current git settings.} } \value{ An entry to the badge section of the README of the repository. - Otherwise, a print of the markdown text for the status badge. +Otherwise, a print of the markdown text for the status badge. } \description{ Add badges to README diff --git a/man/add_contributing.Rd b/man/add_contributing.Rd index 85fab8e..d57d1a1 100644 --- a/man/add_contributing.Rd +++ b/man/add_contributing.Rd @@ -11,7 +11,7 @@ add_contributing(repo = NULL) on current git settings.} } \value{ -A CONTRIBUTING.md file in the `.github` directory +A CONTRIBUTING.md file in the \code{.github} directory } \description{ Add contributing markdown diff --git a/man/add_issue.Rd b/man/add_issue.Rd index 5168cf7..f6d3fb5 100644 --- a/man/add_issue.Rd +++ b/man/add_issue.Rd @@ -8,8 +8,8 @@ add_issue_template(issue, path = ".github/ISSUE_TEMPLATE", overwrite = FALSE) } \arguments{ \item{issue}{A character value of type of issue template to create. Choices -are *"initial-cran-release"*, *"update-cran-release"*, -*"submission-cran"*, and *"acceptance-cran"*.} +are \emph{"initial-cran-release"}, \emph{"update-cran-release"}, +\emph{"submission-cran"}, and \emph{"acceptance-cran"}.} \item{path}{Path to file to add issue template into. Set to ".github/ISSUE_TEMPLATE" which is the default location specified by @@ -19,7 +19,7 @@ GitHub.} name is found, should it be overwritten? Default to FALSE.} } \value{ -A specified issue template markdown file in the specified `path`. +A specified issue template markdown file in the specified \code{path}. } \description{ Add issue templates diff --git a/man/add_logo.Rd b/man/add_logo.Rd index cf8168d..c41757c 100644 --- a/man/add_logo.Rd +++ b/man/add_logo.Rd @@ -12,7 +12,7 @@ on current git settings.} } \value{ An entry to the first level header section of the README of the - repository. +repository. } \description{ Add HTML snippet for package hex sticker in README diff --git a/man/figures/logo.png b/man/figures/logo.png new file mode 100644 index 0000000..83249f2 Binary files /dev/null and b/man/figures/logo.png differ diff --git a/man/pakete.Rd b/man/pakete.Rd index 6074a9d..17bb603 100644 --- a/man/pakete.Rd +++ b/man/pakete.Rd @@ -9,6 +9,8 @@ usual development tools. These are mostly linked to personal preferences during the development process. They assist in making routine and repetitive tasks easily implementable.} \description{ +\if{html}{\figure{logo.png}{options: style='float: right' alt='logo' width='120'}} + Tools and utilities for package development currently not available from usual development tools. These are mostly linked to personal preferences during the development process. They assist in making routine and repetitive tasks easily implementable. } \author{ diff --git a/tests/spelling.R b/tests/spelling.R new file mode 100644 index 0000000..6713838 --- /dev/null +++ b/tests/spelling.R @@ -0,0 +1,3 @@ +if(requireNamespace('spelling', quietly = TRUE)) + spelling::spell_check_test(vignettes = TRUE, error = FALSE, + skip_on_cran = TRUE)