-
Notifications
You must be signed in to change notification settings - Fork 5
/
contribution_instructions.Rmd
126 lines (68 loc) · 7.65 KB
/
contribution_instructions.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
---
title: "Instructions for contributing scripts through GitHub"
output: github_document
editor_options:
chunk_output_type: console
---
```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
```
**Notes:**
* If you would prefer not to use GitHub, you can submit a zip file with your script, instructions, and any associated files to [email protected] and we will upload it to the repository.
* If you previously forked the Motus repository to make earlier changes and are now making new changes later, you should keep your fork current in case others have made changes in the interim to the repository.
## 1. Create a GitHub account and install Git
If you do not already have one, you will need to create a free [GitHub account](https://github.com/). You will also need to [install Git](https://git-scm.com/download/), a version control system that helps groups work collaboratively.
### Windows
You can download Git for Windows [here](https://git-scm.com/download/). When installing Git, select "Git from the command line and also from 3rd-party software" when "adjusting you PATH environment". "Use Git from Git Bash only" also works in this instance. Otherwise, accept the defaults.
### MacOS
You can install Git through [Homebrew](https://brew.sh/), a package manager for command line programs on Mac. Open the terminal (`~/Application/Utilities/Terminal.app`) and enter the following into the terminal:
`/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"`
Press "enter", then type the following into the terminal:
`brew install git`
### Connect Git and GitHub
Now that you have Git installed and a GitHub account, you need to connect the two. In RStudio, click on **Tools > Terminal > New Terminal** to launch a shell within RStudio. Check that you are in a Git Bash shell by entering the following:
`$ echo $SHELL`
Which should result in:
`/usr/bin/bash`
Then enter the following code in the shell and make sure you use the email associated with your GitHub account:
> `git config --global user.name 'your GitHub username'`
> `git config --global user.email '[email protected]'`
You only need to do this once when you first install Git. You can check that it worked with:
> `git config --global --list`
## 2. Fork a copy of the Motus community repository
Forking means making a copy of a repository so that you can make changes without affecting the original repository. Then once you are ready to submit your script to the Motus community repository, you can submit a pull request to merge your copy with your new script to the original repository.
### Fork the repository on GitHub
Navigate to the [Motus community repository](https://github.com/MotusWTS/Motus-community-scripts) and click on the **Fork** button in the top right corner of the page.
Now you can navigate to your fork (copy) of the Motus community repository on your GitHub page.
### Sync your fork with RStudio
You can sync your fork of the Motus community repository with RStudio, so that it is easier to work on and test code, and you'll also have a local copy of the files on your computer. On the page for your fork of the repository on GitHub, click on the green **Code** button in the upper right of the page.
Then under **Clone with HTTPS** there is a URL for the repository. Copy this URL. Now open RStudio and click **File > New Project > Version Control > Git**, then paste the URL into the **Repository URL** field and select the folder on your computer where you want the local copy of the repository to be saved. The **Project directory name** field should autofill. Once the files have finished copying to your computer, you should have a **Git** tab in the upper right window of RStudio and the files should be on your computer. Now you can start adding your script!
## 3. Create a new folder for your script
On your computer, navigate to the local copy of the repository using your usual File Explorer. Open the `contributed-scripts` folder and you should see folders other Motus users have added with their scripts. Add a folder for you script and name it according to the topic of your script (i.e. stopover length, encounter histories, detection maps, etc.). Save your script (preferably as a `.Rmd` RMarkdown file, but `.R` scripts are acceptable too) in your new folder. You can continue to work on and make changes to your script here if needed, as long as you continue to save the most recent version in the folder you created in your copy of the Motus community repository. Please make sure your code is well annotated and that you include instructions on using your code, so that other Motus users are able to understand what your code does.
## 4. Commit/pull/push your additions to your GitHub
Now you've added your script to your local copy of the repository, but you still need to upload your changes to your fork on your GitHub before you can merge them with the original on the Motus community scripts repository page. In RStudio, select the **Git** tab and you will see a list of files in your local copy of the repository. Select the checkbox(es) of the file(s) you added. The yellow question mark boxes will change to a green A (for "added") if it is a file that hasn't yet been uploaded to GitHub. If you have uploaded a previous version of this file to GitHub, you'll see a blue M (for "modified").
Then click on **Commit**.
This will open a new window. Enter a short commit message describing what you added or modified and press **Commit**.
It's good practice to make sure no one else has made changes to the file before you "push" your changes to GitHub. Since you are working on your fork of the repository, chances are that you are the only one working on your fork. Nevertheless, it doesn't hurt to check. "Pull" the most recent version of the GitHub repository (your fork on your GitHub page) onto your local copy on your computer by clicking on **Pull**.
You should see a new window that states that the local copy is up to date.
Now you can push your changes to your fork of the repository on GitHub.
Now you are ready to share your script in the main Motus community scripts repository on the MotusWTS GitHub page.
## 5. Make a pull request to merge with the original repository
Navigate to your fork of the Motus community scripts repository. Above the list of files there are two buttons---click on **Pull request**.
On the **Compare changes** page, you should see four drop-down lists, if you only see two, click **compare across forks**. In the **base repository** drop-down list, select the original Motus community scripts repository. In the **head repository** drop-down list, select your fork, then under **compare**, select the branch you made your changes in.
Click **Create pull request** and write a title and description for your pull request so that the folks at Motus know what you are contributing. Once received, Motus will push your contribution to the main repository so that others can benefit from your code.
## Resources
The following resources were useful in compiling these instructions and offer further in-depth reading on using GitHub and syncing Git and GitHub with R:
* [Happy Git and GitHub for the useR](https://happygitwithr.com/)
* [Intro to GitHub for version control](https://ourcodingclub.github.io/tutorials/git/)
* [Creating a pull request from a fork](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork)