-
Notifications
You must be signed in to change notification settings - Fork 9
/
contributing.qmd
167 lines (106 loc) · 9.2 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
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
# Contributing to this Wiki
Thank you for considering making a contribution to the PennSIVE wiki! In this article, you will find a streamlined set of steps that you will need to follow in order to contribute your own article to the PennSIVE wiki website.
The requirements to follow this tutorial are:
- A [GitHub account](https://github.com/join).
- Have [Quarto](https://quarto.org/docs/get-started/) installed (comes with the latest version of Rstudio).
- Have [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) installed.
- Basic [markdown syntax](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) knowledge.
In essence, making a contribution to this Wiki will involve writing or editing Markdown files and running a few git commands to integrate your changes with the existing wiki. Don't worry you got this!
## 1. Fork and clone the wiki repo
The first step to collaborate on any project that is hosted on GitHub (e.g., this wiki) involves "forking". Forking a GitHub repository (or repo for short) allows you to create your own personal copy of a project under your GitHub account. This forking mechanism allows you to back up changes you make to this wiki's code without affecting the original repository.
To fork this wiki's source code, follow these steps:
1. Navigate to `https://github.com/pennsive/pennsive.github.io` while logged in to GitHub.
2. Click `Fork` on the upper right hand corner. 
After forking, you can check your personal copy of the wiki's source code under this URL: `https://github.com/<your-username>/pennsive.github.io`.
3. Then, clone your copy of the repository from GitHub onto your local machine. In a [Terminal](https://support.apple.com/guide/terminal/open-or-quit-terminal-apd5265185d-f365-44cb-8b09-71a064a42125/mac), run:
```sh
git clone https://github.com/<your-username>/pennsive.github.io
```
This will create a folder called `pennsive.github.io` at the location where you run this command.
## 2. Link your local copy to the `upstream` repository
GitHub allows you to have remote copies of your git repositories. By convention, your personal **remote** copy of a git repository is called `origin`. For projects you do not own (e.g., forked projects), there is one more remote copy that you should track: the original repository, which by convention is called `upstream`.
To track the original PennSIVE wiki repository as the `upstream` repository, you can run:
```sh
cd pennsive.github.io # to get into the project folder
git remote add upstream https://github.com/pennsive/pennsive.github.io.git
```
Tracking the `upstream` repo will allow you to incorporate incoming changes while you work on your contribution article. Find more details on how this is done in this article [TODO: link to section in git article]
## 3. Create your own branch
To keep your work organized, you will use a branch. A branch is essentially an alternative version of your repository. For more details check the git article [TODO: add link].
```sh
git checkout -b <yourusername> # if you're making multiple contributions, work on each in a separate branch and give each one a specific name
```
Technically, you *could* work on the `main` branch instead of creating another branch for your work. However, branches allow you to incorporate changes easily in the event the `main` branch of the `upstream` changes (see rebasing [TODO: add link]). And you **will** need to be in sync with `upstream` when contributing your own work. So be safe: use branches.
## 4. Work on your contribution article
Once you are in your own branch——check that the terminal shows your branch name within parentheses——you're ready to make changes.
In Rstudio, create a Quarto Document (i.e. a file with `.qmd` extension).
The first line of your document should be a top-level header with '#'. This header will be the title of your article, which shows up in the navigation bar of the website. Note that you should not have a YAML section in your document as it is commonly found in Rmarkdown/Quarto documents. For illustration purposes, suppose your document is named `article.qmd` with a header `# Doing cool stuff`. Then your newly created document would look like this:
```R
# Doing cool stuff
```
To add the article to the navigation bar, edit the file `_quarto.yml` by adding the line `- article.qmd` under the `contents` section of the `sidebar` section. It will look something like this (`...` represents omitted content):
```sh
# ...
website:
# ...
sidebar:
# ...
contents:
# ...
- article.qmd
# ...
```
Once you have added your article to the list of articles in `_quarto.yml` as described, you can preview the site by running `quarto render` in the command line **OR** by pressing the render button in Rstudio. Note: you need the latest version of Rstudio, which comes with Quarto, to use the latter method. 
Rendering will create (or update) `.html` files found under the `docs/` directory: these files are the actual content that is viewed in a browser. After rendering, open `docs/index.html` in a browser and navigate to your article using the sidebar. Voila - A preview of your own version of the PennSIVE wiki! 
Once you're familiar with the rendering process, it's time to generate some content!
Write out your contribution article using markdown syntax, version control your work throughout if possible, and follow the next step when you're ready to submit your work.
## 5. Integrate your work with the PennSIVE wiki
We will follow a common Git workflow to incorporate our changes to the live wiki. Before commiting your files, make sure you have rendered and previewed the results (there should be changes to the `docs/` directory if you run `git status`)
### Commit your work on your branch
First you need to make sure all your work is safe by committing it. To commit [TODO: add link] your work, first add your file to the staging area [TODO: add link].
```sh
git add article.qmd docs/article.html # replace 'article' by your file name
```
Then, add all other files that have been updated, this will include the `_quarto.yml` file .
```sh
git add -u # -u adds files that are already tracked in the repo and that have been modified
```
Once all the necessary files are in the staging area, go ahead and commit. Note: make sure that you are **in your own branch** and **NOT** on the `main` branch.
```sh
git commit -m 'some descriptive message'
```
Back up your changes to GitHub before continuing:
```sh
git push origin <your-branch>
```
### Updating main (if needed)
You will need to incorporate any changes made to the wiki that may have happened after you forked. To check if changes have been made to the wiki, you need to `fetch` the metadata from the `upstream` repository.
```sh
git checkout main # you should not have uncommitted work before switching to main
git fetch upstream main
```
Once the metadata has been `fetch`ed, check if your main branch is up to date
```sh
git status
```
If the resulting message says 'up to date' you can skip to (TODO: submitting a pull request). If not follow this process:
```sh
git pull upstream main
git checkout <your-branch>
git merge main
```
These three commands will (1) update your `main` branch to match what is in the original repository you once forked, (2) merge the updated changes from the `main` branch to `<your-branch>`. You may need to resolve merge conflicts [TODO: add link] which falls out of the scope of this. However, here's some additional resources (TODO)
### Submitting a Pull Request
After merging potential updates to the wiki as described above (or if that step was not needed), you can go ahead and push the final version of your work to GitHub.
```sh
git push origin <your-branch>
```
Once that is successful, navigate to your GitHub account and start a **Pull Request**. In your copy of the repository, you will see a green button to start a pull request. As an example, here's the pull request for the article you are currently reading.
Clicking on the `Compare & pull request` will take you to a page in the PennSIVE repo where you can describe your edits. Check that the name of your branch appears on the right (see underlined) and the main branch of the PennSIVE repo on the left. Then, include a descriptive summary of your proposed changes/additions. Finally, hit 'create pull request'.
.
Once you have submitted your pull request, the site maintainer will review your changes and either accept them or ask for more edits. The status of the pull request will be publicly visible on the PennSIVE repo. If more edits are required, make more commits to your branch, push them to your repo, and these changes will appear in your pull request.
## Congratulations
You have made a contribution to the PennSIVE wiki and made the world a better place!