-
Notifications
You must be signed in to change notification settings - Fork 46
/
contributing.Rmd
176 lines (130 loc) · 7.92 KB
/
contributing.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
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
---
title: "Contributing to Open Source Football"
description: |
A brief guide how to contribute content.
author:
- name: Sebastian Carl
url: https://twitter.com/mrcaseb
affiliation: nflfastR
affiliation_url: https://twitter.com/nflfastR
date: 01-21-2022
repository_url: "https://github.com/nflverse/open-source-football"
output:
distill::distill_article:
toc: true
toc_depth: 3
---
```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
```
## Preface
The primary goal of Open Source Football is to make football-related analysis and
corresponding code publicly available. To achieve this, we need volunteers
who are willing to make a contribution.
Articles posted on Open Source Football are authored using [Distill for R
Markdown](https://rstudio.github.io/distill). If you would like to contribute,
you'll need to have installed R and R Markdown. However, this **does not
mean that are limited exclusively to R code** because R Markdown
[supports many other languages as well](https://bookdown.org/yihui/rmarkdown-cookbook/other-languages.html)!
You'll need R and R Markdown to create the post and the formal structure but the
most important thing - your code and its output - can be anything compatible with R
(please see [Ben's python contributing example](https://www.opensourcefootball.com/posts/2020-08-20-python-contributing-example/)).
This guide is intended to help all contributors prepare articles for
publishing. If you have questions or think something is unclear or wrong please [create an
issue](https://github.com/nflverse/open-source-football/issues/new) and we will
look into it.
## Brief Overview
Here is a very brief overview of what is needed. The next section will have much
more detail on each of these steps.
The steps below assume that
you have [RStudio](https://rstudio.com/) and git (I highly recommend [Hadley's
git section](http://r-pkgs.had.co.nz/git.html) in "R packages") installed.
Contributing to someone else’s package or project became much more convenient with the [usethis pull request helpers](https://usethis.r-lib.org/articles/pr-functions.html). We will use these in the following sections, so please read the linked article.
1. Install the R packages you will need to contribute (**Note the minimum version requirement of distill**)
1. [Fork the website repository to your GitHub (you'll need a free account) and clone it to your local computer](https://usethis.r-lib.org/articles/pr-functions.html#fork-and-clone)
1. [Create a new branch](https://usethis.r-lib.org/articles/pr-functions.html#branch-then-make-your-change)
1. Create the new article (see [the
repo](https://github.com/nflverse/open-source-football/tree/master/_posts) for
some examples and check the [Distill for R
Markdown](https://rstudio.github.io/distill) website) and please don't forget
to add [metadata and chunk options](#start-working-on-the-post) as discussed
in the next section
1. Commit all to your post related files
1. Submit the pull request and let us review your code https://usethis.r-lib.org/articles/pr-functions.html#submit-pull-request
(please see [Push your work into your repo](#push-your-work-into-your-repo)
for details what you should do to **avoid merge conflicts**)
With the last step we will be notified and will take a look at your article,
suggest changes as necessary, then publish it when it’s ready by merging it into
the main repository.
## More Detailed Instructions
Before you start, don't forget to read the article on [usethis pull request helpers](https://usethis.r-lib.org/articles/pr-functions.html).
### Install the packages
Install the packages `distill`, `usethis` and `rmarkdown` with
```{r, eval=FALSE}
install.packages(c("distill", "usethis", "rmarkdown"))
```
**Important!**
Rendering of the site will fail or be incomplete if an outdated version of `distill` is installed, so please check if you have installed `distill >= 1.0` by running
```{r, eval=TRUE}
paste0("You are running distill v", utils::packageVersion("distill"))
```
### Fork and Clone the Repository
The "Fork" is your own copy of the Open Source Football Github Repository. You can clone it to get your own local copy. There are many ways to accomplish these two steps, but I highly recommend
```{r, eval=FALSE}
usethis::create_from_github("nflverse/open-source-football")
```
This will fork the repo, clone it to your computer and open the project in a new RStudio session. [Click here for more details](https://usethis.r-lib.org/articles/pr-functions.html#fork-and-clone).
### Create a new Branch and Start Working
The process of contributing starts now by creating a new branch (please try to choose a descriptive name). It is good practice to make your changes in a new branch instead of the main branch, so please make sure not to skip this step.
```{r, eval=FALSE}
usethis::pr_init(branch = "bens-apa-tiers")
```
[Click here for more details](https://usethis.r-lib.org/articles/pr-functions.html#branch-then-make-your-change).
### Start working on the post
Create the new article by running
```{r, eval=FALSE}
distill::create_post("Title of your post")
```
This will create a new folder in `_posts` and name it with the current date and
your chosen title. Additionally the RMarkdown file in which you will write your
post will be opened automatically. It will look something like this
```{r, echo=FALSE, fig.align='center'}
knitr::include_graphics("https://user-images.githubusercontent.com/38586519/90627998-1dcb1980-e21d-11ea-8ea9-e307f81087c4.png")
```
We need to tweak the metadata as well as the chunk setup a little bit in order
for the post to meet our expectations. Please have a look at [example
file](https://github.com/nflverse/open-source-football/blob/master/_sample_meta_and_options.Rmd)
for a little template.
```{r, echo=FALSE, fig.align='center'}
knitr::include_graphics("https://user-images.githubusercontent.com/38586519/90628632-3e47a380-e21e-11ea-9bae-a01ac6720026.png")
```
Now you are ready to write your post. Please see [Distill for R
Markdown](https://rstudio.github.io/distill) as well as some of [the
already published posts](https://github.com/nflverse/open-source-football/tree/master/_posts).
And if you feel like you need more information about R Markdown please feel free
to check the [R Markdown Cookbook](https://bookdown.org/yihui/rmarkdown-cookbook/).
### Commit your Changes in your Branch
Using git within RStudio is easy because you can do it graphically. However, it
doesn't make sense to provide a ton of screenshots and text here. Instead I
recommend two sources:
* The short one is [happygitwithr.com](https://happygitwithr.com/rstudio-git-github.html)
* The detailed one is [Hadley's section](http://r-pkgs.had.co.nz/git.html)
Commit all files **which are related to your post** and go on with the last step.
There are 4 files not related to your post which may cause merge conflicts when you push
them without updating them before your pull request. To avoid this, **please run the
following code right before you commit all your files:**
```{r, eval=FALSE}
source("https://raw.githubusercontent.com/nflverse/open-source-football/master/_update_con_files.R")
```
If you forget this step, you can still create the pull request and GitHub
will inform you of the conflicts. If there are conflicts, run the above line, then commit and
push the updated files: `docs/index.html`, `docs/index.xml`, `docs/posts/posts.json`, and
`docs/sitemap.xml`.
### Submit the Pull Request
The following code pushes any local changes of your code to GitHub and puts you in position to make your pull request:
```{r, eval=FALSE}
usethis::pr_push()
```
This launches a browser window with the prepared pull request on Github. **You will have to click "Create pull request"**, add some description, and finally submit it.
[Click here for more details](https://usethis.r-lib.org/articles/pr-functions.html#submit-pull-request).
Now you are done. We will start reviewing your pull request and make sure to publish it. Thanks for your contribution!