Skip to content
Snippets Groups Projects
repoAsATemplate.md 2.81 KiB
Newer Older
Ben Anderson's avatar
Ben Anderson committed
## Repo as a template

There are as many templates for (R) repos as there R users... Here's ours.

B.Anderson's avatar
B.Anderson committed
### Structure

Ben Anderson's avatar
Ben Anderson committed
We structure the repo as a package. We may never build it but usually we do so that the package functions are available everywhere in it
Ben Anderson's avatar
Ben Anderson committed

Things you should touch:

| Item        | Description  |
| --- | --- |
| **[.gitignore](.gitignore)** | A place to tell git what _not_ to synchronise e.g. `.csv` or [weird OS files](https://gist.github.com/adamgit/3786883)|
| **[analysis/](analysis/)** | Where we store .Rmd files and the .R scripts that call them (usually using a `drake` plan) |
Ben Anderson's avatar
Ben Anderson committed
| **[DESCRIPTION](DESCRIPTION)** | But only if you use this as a template for your own repo - it is a special file for packages |
| **[docs/](docs/)** | Where we put output generated by the .R/.Rmd code. This is helpful if you are using [github/lab pages](https://guides.github.com/features/pages/). Unfortunately the University of Southampton gitlab service does not currently support this. |
| **[env.R](env.R)**  | Where we store all the parameters that might be re-used across our repo. Such as colour defaults, data paths etc. We avoid using a project/repo level .Rprofile because it can lead to [a **lot** of confusion](https://support.rstudio.com/hc/en-us/articles/360047157094-Managing-R-with-Rprofile-Renviron-Rprofile-site-Renviron-site-rsession-conf-and-repos-conf). |
| **[LICENSE](LICENSE)** | Edit to suit your needs |
| **[notData/](notData/)** | Where we do not store data. R packages expect certain kinds of data in their 'data/' folders. Do not put your data in it. |
| **[R/](R/)** | Where we store functions that get built |
| **[README.md](README.md)** | Repo readme |
| **[resources.md](resources.md)** | Our collection of guides and `how-tos` |
| **[template.md](template.md)** | This file |

Ben Anderson's avatar
Ben Anderson committed
More on data:
B.Anderson's avatar
B.Anderson committed

> We recommend **not** putting your data in your repo at all. 
B.Anderson's avatar
B.Anderson committed
Yes, this breaks true reproducability but there are reasons:
Ben Anderson's avatar
Ben Anderson committed
 * we often use data that is commercial or sensitive or personal (under GDPR) - so we cannot risk that leaking out
 * we often use _very large_ datasets which most git/hub/lab services sensibly reject
 * we often pull real time data on the fly from elsewhere so storage makes no sense 
        
Things you should not touch:
Ben Anderson's avatar
Ben Anderson committed

Ben Anderson's avatar
Ben Anderson committed
| Item        | Description  |
| --- | --- |
| **man/** | Created by building the project/package using roxygen2 |
B.Anderson's avatar
B.Anderson committed
| **NAMESPACE** | - ditto - |
| **.Rbuildignore** | - ditto - |
B.Anderson's avatar
B.Anderson committed

### Our coding habits

We try to remember to call functions using `woRkflow::myFunction()` so we know exactly which package we are using. This also forces regular package re-builds so your new fancy updated function can be used.

We defer to the [tidyverse style guide](https://style.tidyverse.org/) on many things although we do prefer using `camelCase` rather than `inserting_hyphens` in function and variable names.