A brief guide how to contribute content.
The key idea of Open Source Football is to make football related analysis and the 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. If you would like to contribute you’ll have to have installed R and R Markdown. However, this expressly does not mean that we want to limit ourselves exclusively to R code because R Markdown supports many other languages as well! You’ll need R and R Markdown to create the post and the formal structure but the most important thing - your code and it’s output - can be anything you want (please see Ben’s python contributing example).
This guide is intended to help all contributors to get their articles ready for publishing. Since all of this is very new it’s a work in progress and if I see typical problems I will update this site with the corresponding solutions. If you have questions or think something is unclear or wrong please create an issue and I will look into it.
If you are willing to contribute you will have to follow the below steps (we will discuss some steps more detailed in the next section). Please note we assume that you have RStudio and git (I highly recommend Hadley’s git section in “R packages”) installed.
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 repo.
Install the packages distill
and rmarkdown
with
install.packages(c("distill", "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
paste0("You are running distill v", utils::packageVersion("distill"))
[1] "You are running distill v1.2"
Login to your GitHub account, view the website repo and fork it by clicking the “Fork” button. The current version of the repo will be copied into your GitHub.
Create a new branch within your repo and try to choose a descriptive name
Copy the web url of the new repo into your clipboard
In RStudio choose Create a Project > Version Control > Git, paste the Repository URL from above and click “Create Project”. The whole thing will be downloaded and the project opened.
Important: Make sure you switch into your newly created branch from the previous section!
For further information please visit happygitwithr.com.
Create the new article by running
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
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 for a little template.
Now you are ready to write your post. Please see Distill for R Markdown as well as some of the already published posts. And if you feel like you need more information about R Markdown please feel free to check the R Markdown Cookbook.
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:
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 causing 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.
source("https://raw.githubusercontent.com/mrcaseb/open-source-football/master/_update_con_files.R")
Never mind if you forget that. You can create the pull request anyway and GitHub will inform you if there are conflicts. Just run the above lines and commit and push the updated files docs/index.html
, docs/index.xml
, docs/posts/posts.json
, docs/sitemap.xml
.
To create the Pull Request visit your GitHub repo and you will notice a banner indicating that you’ve recently pushed a new branch and that you can “compare & pull request”. Follow the steps for creating a pull request from a fork and you are finally done.
If you see mistakes or want to suggest changes, please create an issue on the source repository.
Text and figures are licensed under Creative Commons Attribution CC BY-NC 4.0. Source code is available at https://github.com/mrcaseb/open-source-football, unless otherwise noted. The figures that have been reused from other sources don't fall under this license and can be recognized by a note in their caption: "Figure from ...".