-
Notifications
You must be signed in to change notification settings - Fork 0
/
contributing.qmd
135 lines (71 loc) · 7.96 KB
/
contributing.qmd
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
# Contributing Guidelines
This resource is created in mind so that the community that uses it, can also contribute to it. We hope this mindset will encourage the resource to grow and stay up-to-date for R learners.
Importantly, **all skill levels** are welcome to contribute, even if you think your skills are not up to scratch - this is what this guide is for! There is also a way for you to contribute [if code/git/Quarto is not your cup of tea](#sec-noncode-contributions).
### Hello Quarto!
This book is built by [Quarto](https://quarto.org/) which is an open source, cross-language publishing system that allows users to build beautiful things from blogs, to websites and books!
You can learn more about the capabilities of Quarto in [this talk](https://www.youtube.com/watch?v=p7Hxu4coDl8) by Mine Çetinkaya-Rundel & Julia Stewart Lowndes at posit::conf(2023)
#### Install Quarto {#sec-installquarto}
First things first, let's make sure we have the latest version of Quarto installed using these [instructions](https://quarto.org/docs/get-started/)
### GitHub Workflow {#sec-githubworkflow}
Next, we need to talk about the Git/GitHub part of the workflow. Git is a **version control** system. It that **tracks changes in our code** that generated this book and helps us **coordinate our collaborative edits**.
Git monitors the changes in a project directory a.k.a **repository** or "repo". There are two types of repositories:
- **Local** repository: This is a project directory that exists *locally* in your computer than git is actively watching over.
- **Remote** repository: This is a **synced** copy of your local repo. The [remote repo](https://github.com/unsw-edu-au/r4psych) for this book lives on GitHub. GitHub **centralises** our collaborative efforts. It provides a platform for the community to make a local copy of the book, create changes and introduce them back to the remote repository. GitHub also acts as the hosting service for the book itself which is also a big bonus for us.
::: {.callout-tip}
A great resource on GitHub setup and collaboration is [Happy Git with R](https://happygitwithr.com/), which includes fantastic background philosophy as well as tips for set-up, workflows, and collaboration.
:::
#### Sign up to GitHub
Start by getting yourself an account at GitHub [by signing up here](https://github.com/signup)
#### Install git {#sec-installgit}
Follow [these instructions](https://happygitwithr.com/install-git) from "Happy Git with R" to install git to your computer. There are specific instructions for different operating systems.
#### Install a git client {#sec-installgitclient}
Traditionally, git has been used in the shell terminal. This is the 'back-end' of the computer and allows you to interact with your computer using code. This means that you have to type out commands to tell git what to do. This approach can become a little overwhelming when you are starting out.
Instead, we suggest using a git client like [Github Desktop](https://desktop.github.com/), however it is limited to only to Windows and Mac. If you use Linux, [GitKraken](https://www.gitkraken.com/git-client) is also a great alternative. There are many [git clients to choose from](https://git-scm.com/downloads/guis). Once you start to get the hang on things, all of these clients are much of the same and its a matter of personal preference.
If you are an RStudio user, there is a [built-in git tab ](https://jennybc.github.io/2014-05-12-ubc/ubc-r/session03_git.html#configurerstudio) to the interface, its features are more simplified than the previously mentioned clients but does the basic commands that we will talk about next.
Once you have downloaded a client, follow it's instructions to login and connect your Github account to the client.
::: callout-note
For the rest of the chapter, we will focus on using Github Desktop, but the main git commands should translate to whichever client you are using.
:::
### The Contributor's workflow
We will work on forks (independent copies of the book) so as to not overwrite each other’s work and have a systematic way in introducing new contributions to the book. Coordinating collaborative changes on the same project is what GitHub does best.
The `main` branch is currently the most recent approved version of the book - this is displayed at https://unsw-edu-au.github.io/r4psych/
The contributing workflow looks like this:
1. You fork the most recent version from `main`
2. You make your edits, you **commit** regularly, you **push** regularly to the remote (github.com)
3. When you are happy with your changes, you will create a **pull request** for your contribution and one of the core maintainers will review it. Edits may be requested or one of the maintainers will make the changes after having a conversation with you.
4. Once everything and everyone is happy and dandy with the final changes, your changes will be **approved and merged into main**. When this happens, your branch is deleted on the remote and you will also delete it locally.
Now let's walk through this workflow step by step
::: {.callout-note}
The following sections assumes you’ve completed the initial set-up of [installing git](#sec-installgit) and a [git client](#sec-installgitclient)
:::
#### Fork: Create an independent copy of the book
Now that we have all the installation out of the way, we can get started!
The best way to contribute to the book is to create an independent copy that lives in your Github account. This process is called **creating a fork** and it allows you to make your contributions without it affecting the approved version of the book.
1. To create a fork, head over to the [remote repo for the book](https://github.com/unsw-edu-au/r4psych) and click on the **Fork** button on the right hand side of the webpage
2. Continue to the next webpage and leave the default settings as they are and click the green button *Create fork*
Forking will create a duplicate of the `r4psych` book remote repo into your account. This is **your** remote copy that you can make your contributions to. We will talk about how we bring your contributions back to the `r4psych` remote repo later in [Create a pull request](XX).
#### Clone: Create a local copy of your fork
Once you have a fork, we will get a local copy of the book onto your computer by "cloning" the forked repository.
1. Head to the webpage of your forked repository. The URL for it should look something like: **https://github.com/your-usename/r4psych**
2. Click on the big green button that says **Code**
Here you will find a drop-down menu showing different methods of cloning the code from the remote repo.
We will **stick with the default option of using HTTPS** a.k.a. cloning by using the URL of the remote repo.
3. Click on the copy URL button (The stacked squares icon)
4. Navigate to Github Desktop and click on the first drop down menu from the left. Here you will find the **Add** button.
5. Click on **Add** and then **Clone Repository**
6. Click on the **URL** option and paste in the URL of your fork's remote repo e.g. **https://github.com/your-username/r4psych**
7. Under **Local Path**, you can choose where you want to place this cloned repo. Avoid putting your repos in Cloud services such as Dropbox or Google Drive. These can sometimes interfere with git's ability to track your changes.
8. Finally, click **Clone** and let git do the work! It will copy everything that is in the remote repo and bring it down locally on your computer!
9. Navigate to the local path where you told git to clone to in Step 7 and check out the directories. You will learn more about these in [Book Structure](#sec-bookstructure)
#### Make your changes
#### Push your work to remote
#### Create a pull request
### `{renv}`: Managing R packages
#### `{renv}` workflow
### Book Structure {#sec-bookstructure}
#### Book Practices and Conventions
### Can I make a contribution without using Git? {#sec-noncode-contributions}