-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathREADME.Rmd
117 lines (94 loc) · 5.03 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
<!-- README.md is generated from README.Rmd. Please edit that file -->
# pkgTemplateR `r badger::badge_custom("dev version", as.character(packageVersion("pkgTemplateR")), "blue", "https://github.com/CTU-Basel/pkgTemplateR")` [](https://ci.appveyor.com/project/CTU-Basel/pkgTemplateR) [](https://api.travis-ci.com/CTU-Basel/pkgTemplateR.svg?branch=master) [](https://codecov.io/github/CTU-Basel/pkgTemplateR)
**Template created by Patrick R. Wright**
If you would like to make use of this template just click the green
"Use this template" button or use [this link](https://github.com/CTU-Basel/pkgTemplateR/generate)
to it and set up your new R package repository as usual on GitHub.
If you want to work with the continuous integration (CI) modules you
will need to grant [travis](https://travis-ci.com/) and [AppVeyor](https://ci.appveyor.com)
access to your repository. The config files ([.travis.yml](.travis.yml),
[appveyor.yml](appveyor.yml)) for travis and AppVeyor are already in the repository.
GitHub actions builds have already been set up too. They will check if the
package runs on Linux, Windows and macOS. Furthermore they will render
the pkgdown page. For the packagedown page you will need to configure
the GitHub Pages part in the Settings to use the gh-pages branch and the
root directory within.
You will also need to search and replace all occurences of `pkgTemplateR` with
the name that you have chosen for your R package.
## Installing from GitHub with devtools
```{r, eval = FALSE}
devtools::install_github("CTU-Basel/pkgTemplateR")
```
## Basic usage
Load the package
```{r, echo = TRUE, warning=FALSE, message=FALSE}
# load the package
library(pkgTemplateR)
# internal file of the package
path <- system.file("exdata", "file.txt",
package = "pkgTemplateR")
# print it
print_file_content(file_path = path)
```
## For contributors
### Testing with devtools
```{r, eval = FALSE}
# run tests, this assumes you are one directory up from the pkgTemplateR dir
devtools::test("pkgTemplateR")
# spell check
# ignore words character vector allows to exclude technical terms in the check
ignore_words <- c()
devtools::spell_check("pkgTemplateR", ignore = ignore_words)
```
### Linting with lintr
```{r, eval = FALSE}
# lint the package -> should be clean
library(lintr)
lint_package("pkgTemplateR", linters = with_defaults(camel_case_linter = NULL,
object_usage_linter = NULL,
line_length_linter(125)))
```
### Building the vignette
```{r, eval = FALSE}
library(rmarkdown)
render("vignettes/pkgTemplateR-package-vignette.Rmd",
output_format=c("pdf_document"))
```
### Generating the README file
The README file contains both standard text and interpreted R code.
Changes should be made in the `README.Rmd` file and the file "knited" with R.
In this template the knitting of the Rmd file is performed automatically with
GitHub actions.
### Handling dependencies
Dependencies to other R packages are to be declared in the `DESCRIPTION` file under `Imports:` and in
the specific `roxygen2` documentation of the functions relying on the dependency. It is suggested to
be as explicit as possible. i.e. Just import functions that are needed and not entire packages.
Example to import `str_match` `str_length` `str_wrap` from the `stringr` package:
```{r, eval = FALSE}
#' @importFrom stringr str_match str_length str_wrap
```
### Preparing a release on CRAN
```bash
# build the package archive
R CMD build pkgTemplateR
# check the archive (should return "Status: OK", no WARNINGs, no NOTEs)
# in this example for version 0.0.1
R CMD check pkgTemplateR_0.0.1.tar.gz
```
### Guidelines for contributors
Requests for new features and bug fixes should first be documented as an
[Issue](https://github.com/) on GitHub.
Subsequently, in order to contribute to this R package you should fork the main repository.
After you have made your changes please run the
[tests](README.md#testing-with-devtools)
and
[lint](README.md#linting-with-lintr) your code as
indicated above. Please also increment the version number. If all tests pass and linting
confirms that your coding style conforms you can send a pull request (PR).
Changes should also be mentioned in the `NEWS` file. A test has been implemented
to remind you to make these changes (see [here](tests/testthat/test-version_diff.R)).
The PR should have a description to help the reviewer understand what has been
added/changed. New functionalities must be thoroughly documented, have examples
and should be accompanied by at least one [test](tests/testthat/) to ensure long term
robustness. The PR will only be reviewed if all travis, AppVeyor and GitHub actions checks are successful.
The person sending the PR should not be the one merging it.