---
title: "Setting up your computer for WORCS"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Setting up your computer for WORCS}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

This is a tutorial on how to set up your personal computer for use with the `worcs` package. It guides you through the installation of several software packages, and registration on GitHub. This vignette does not assume a prior installation of `R`, so it is suitable for novice users.
You only have to perform these steps once for every computer you intend to use `R` and `worcs` on, and the entire process should take approximately 30 minutes if you start from scratch.
In case some of the software is already installed on your system, you can skip those related steps.

Follow these steps in order:

1. Install [R (free)](https://CRAN.R-project.org)
2. Install ['RStudio' Desktop (Free)](https://posit.co/download/rstudio-desktop/)
3. Install Git from [git-scm.com](https://git-scm.com/downloads/). Use the default, recommended settings. It is especially important to leave these settings selected:
    + Git from the command line and also from third party software  
    <!--*The `worcs` R-package calls Git from the command line*-->
    + Use the 'OpenSSL' library  
    <!--*For secure data transfer with GitHub*-->
    + Checkout Windows-style, commit Unix-style line endings  
    <!--*This is the preferred setting when collaborating with others on different platforms. Be prepared that, on windows, you will receive harmless notifications about LF to CRLF line endings.  *-->
    + Enable Git Credential Manager  
    <!--*For logging in to GitHub*-->
    + If you run into any trouble, a more comprehensive tutorial on installing Git is available at [happygitwithr.com](https://happygitwithr.com/install-git.html).
4. Register on 'GitHub' (alternatively: see [this vignette](https://cjvanlissa.github.io/worcs/articles/git_cloud.html) on how to use 'GitLab' or 'Bitbucket')
    + Go to [github.com](https://github.com/) and click *Sign up*. Choose an "Individual", "Free" plan.
    <!-- + Request a [free academic upgrade](https://help.github.com/en/articles/applying-for-an-educator-or-researcher-discount). This allows you to create *private repositories*, which are only visible to you and selected collaborators, and can be made public when your work is published. -->
5. Install all packages required for WORCS by running the code block below this writing in the 'RStudio' console. Be prepared for three contingencies:  
    + If you receive any error saying *There is no package called [package name]*, then run the code `install.packages("package name")`  
    + If you are prompted to update packages, just press [ENTER] to avoid updating packages. Updating packages this way in an interactive session sometimes leads to errors if the packages are loaded.  
    + If you see a pop-up dialog asking *Do you want to install from sources the package which needs compilation?*, click *No*.


```
install.packages("worcs", dependencies = TRUE)
tinytex::install_tinytex()
renv::consent(provided = TRUE)
```

6. Connect 'RStudio' to Git and GitHub (for more support, see [Happy Git with R](https://happygitwithr.com/)
    a. Open 'RStudio', open the Tools menu, click *Global Options*, and click *Git/SVN*
    a. Verify that *Enable version control interface for RStudio projects* is selected
    a. Verify that *Git executable:* shows the location of git.exe. If it is missing, manually fix the location of the file.
    <!-- a. Click *Create RSA Key*. Do not enter a passphrase. Press *Create*. A window with some information will open, which you can close. -->
    <!-- a. Click *View public key*, and copy the entire text to the clipboard. -->
    a. Restart your computer
    <!-- a. Go to [github.com](https://github.com/) -->
    <!-- a. Click your user icon, click *Settings*, and then select the *SSH and GPG keys* tab. -->
    <!-- a. Click *New SSH key*. Give it an arbitrary name (e.g., your computer ID), and paste the public key from your clipboard into the box labeled *Key*. -->
    <!-- a. Open 'RStudio' again (unless it restarted by itself) -->
    a. Run `usethis::create_github_token()`. This should open a webpage with a dialog that allows you to create a Personal Access Token (PAT) to authorize your computer to exchange information with your GitHub account. The default settings are fine; just click "Generate Token" (bottom of the page).
    a. Copy the generated PAT to your clipboard (NOTE: You will not be able to view it again!)
    a. Run `gitcreds::gitcreds_set()`. This should open a dialog in the R console that allows you to paste the PAT from your clipboard.
    a. If you do not have a Git user set up on your computer yet (e.g., if this is the first time you will be using Git), run the following - making sure to substitute your actual username and email:

```
worcs::git_user("your_name", "your_email", overwrite = TRUE)
```

7. Everything should be installed and connected now. You can verify your installation using an automated test suite. The results will be printed to the console; if any tests fail, you will see a hint for how to resolve it. Run the code below this writing in the 'RStudio' console:

```
worcs::check_worcs_installation()
```

### Optional step

If you intend to write documents in APA style, you should additionally install the `papaja` package.
Because `papaja` has many dependencies, it is recommended to skip this step if you intend to write documents in a different style than APA.
Unfortunately, this package is not yet available on the central R repository CRAN, but you can install it from 'GitHub' using the following code:

```
install.packages("papaja", dependencies = TRUE, update = "never")
```
