# Get started with rcompendium

`rcompendium` makes easier the creation of R packages or research compendia (i.e. a predefined files/folders structure) so that users can focus on the code/analysis instead of wasting time organizing files. A full ready-to-work structure is set up with some additional features: version control, remote repository creation, CI/CD configuration (check package integrity under several OS, test code with `testthat`, and build and deploy website using `pkgdown`).

## Prerequisites

Before using the package `rcompendium` you must follow these three steps.

### GIT configuration

First ensure that GIT is correctly installed on your machine and linked to RStudio. Read the Chapter 6 of Happy Git and GitHub for the useR.

You also need to store your GIT credentials locally (i.e. for the project) or globally (recommended). Run `gh::gh_whoami()` to see if your git and associated credentials are correctly configured. You should see something like:

    {
      "name": "John Doe",
      "login": "jdoe",
      "html_url": "https://github.com/jdoe",
      ...
    }

Otherwise you might need to run:

    gert::git_config_global_set(name = "user.name",   value = "John Doe")
    gert::git_config_global_set(name = "user.email",  value = "john.doe@domain.com")
    gert::git_config_global_set(name = "github.user", value = "jdoe")

See `?gert::git_config_global_set` for further information.

### Creating a GitHub repo

To create the GitHub repository directly from R, the package `rcompendium` uses the function `usethis::use_github()`, a client to the GitHub REST API. The interaction with this API required an authentication method: a GITHUB PAT (Personal Access Token).

If you don’t have a GITHUB PAT locally stored, you must:

1. visit the page https://github.com/settings/tokens and create a new token;
2. store it in the `~/.Renviron` file by using `usethis::edit_r_environ()` and adding the following line: `GITHUB_PAT='ghp_99z9...z9'`.

Run `usethis::gh_token_help()` for more information about getting and configuring a GITHUB PAT.

If everything is well configured, you should see something like this after calling `gh::gh_whoami()`:

    {
      "name": "John Doe",
      "login": "jdoe",
      "html_url": "https://github.com/jdoe",
      "scopes": "delete_repo, repo, workflow",
      "token": "ghp_99z9...z9"
    }

Then you will be able to create a GitHub repository directly from R!

### Managing credentials

You can use the arguments `given`, `family`, `email`, and `orcid` directly with the functions `new_*()` and `add_*()`. But if you create a lot a projects (packages and/or compendia) it can be frustrating in the long run.

An alternative way is to use ONCE AND FOR ALL the function `set_credentials()` to permanently store this information in the `~/.Rprofile` file. If these arguments are set to `NULL` while calling any function of the package, `rcompendium` will search their values in this file. It will save your time (it’s the purpose of this package).

Even if you have stored your credentials in the `~/.Rprofile` file you will always be able to modify them on-the-fly (i.e. by using credentials arguments in the functions `new_*()` and `add_*()`) or permanently by re-running `set_credentials()`.

## Usage

The recommended workflow is:

1. Store your credentials with `set_credentials()` (if not already done);
2. IMPORTANT - Create an new empty RStudio project;
3. Run `new_package()` to create a new package structure or `new_compendium()` to create a new research compendium structure;
4. Edit some metadata in `DESCRIPTION`, `CITATION`, and `README.Rmd`;
5. Start working (add data, write and document R functions, etc.);
6. And do not forget to commit your changes.

In addition to these three setup functions (`set_credentials()`, `new_package()`, `new_compendium()`), the package `rcompendium` offers 29 other functions. These can be grouped as:

- `add_*()`: functions to add/update/overwrite files, configuration settings, dependencies, badges, etc.;
- `get_*()`: functions to retrieve some information (available licenses, R version, etc.).

Visit the Reference page for further details.

To sum up

    ## Define ONCE FOR ALL your credentials ----

    rcompendium::set_credentials(given = "John", family = "Doe",
                                 email = "john.doe@domain.com",
                                 orcid = "9999-9999-9999-9999", protocol = "ssh")

    ## CREATE A NEW EMPTY RSTUDIO PROJECT ----

    ## Create an R package structure ----

    rcompendium::new_package()

    ## Then...
    ## ... edit metadata in DESCRIPTION, CITATION, README.Rmd, etc.
    ## ... implement and document R functions in R/

    ## Update functions documentation and NAMESPACE ----

    devtools::document()

    ## Update list of dependencies in DESCRIPTION ----

    rcompendium::add_dependencies()

    ## Check package ----

    devtools::check()

    ## Example: use of an add_*() function ...
    ## ... update 'Number of Dependencies Badge' in README.Rmd ----

    rcompendium::add_dependencies_badge()

N.B. Users can also use functions from the package `usethis` to add some missing features (e.g. `data/` and package release tools).

## Resources

- Developing an R package
- Working with a compendium

## Contributing

You are welcome to contribute to the `rcompendium` project. Please read our Contribution Guidelines.

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

## Colophon

This package is the result of intense discussions and feedback from the training course Data Toolbox for Reproducible Research in Computational Ecology.

`rcompendium` is largely inspired by the package `rrtools` developed by Ben Marwick et al. and tries to respect the standard defined by the community. Special thanks to these developers!