forked from PecanProject/pecan
-
Notifications
You must be signed in to change notification settings - Fork 1
/
01_using-git.Rmd
329 lines (211 loc) · 12.7 KB
/
01_using-git.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
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
### Using Git {#using-git}
This document describes the steps required to download PEcAn, make changes to code, and submit your changes.
* If you are new to GitHub or to PEcAn, start with the one-time set-up instructions under [Before any work is done]. Also see the excellent tutorials and references in the [Git]) section right below this list and at the bootom in [References].
* To make trivial changes, see [Quick and Easy].
* To make a few changes to the code, start with the [Basic Workflow].
* To make substantial changes and/or if plan to contribute over time see [Recommended Workflow: A new branch for each change].
#### Git
Git is a free & open source, distributed version control system designed
to handle everything from small to very large projects with speed and
efficiency. Every Git clone is a full-fledged repository with complete
history and full revision tracking capabilities, not dependent on
network access or a central server. Branching and merging are fast and
easy to do.
A good place to start is the [GitHub 5 minute illustrated tutorial](https://guides.github.com/introduction/flow/).
In addition, there are three fun tutorials for learning git:
* [Learn Git](https:k//www.codecademy.com/learn/learn-git) is a great web-based interactive tutorial.
* [LearnGitBranching](https://learngitbranching.js.org/)
* [TryGit](http://tryk.github.com).
**URLs** In the rest of the document will use specific URL’s to clone the code.
There a few URL’s you can use to clone a project, using https, ssh and
git. You can use either https or git to clone a repository and write to
it. The git protocol is read-only.
This document describes the steps required to download PEcAn, make changes to code, and submit your changes.
If during above process you want to work on something else, commit all
your code, create a new branch, and work on new branch.
#### PEcAn Project and Github
* Organization Repository: https://github.com/organizations/PecanProject
* PEcAn source code: https://github.com/PecanProject/pecan.git
* BETYdb source code: https://github.com/PecanProject/bety.git
These instructions apply to other repositories too.
#### PEcAn Project Branches
We follow branch organization laid out on [this page](http://nvie.com/posts/a-successful-git-branching-model).
In short, there are three main branches you must be aware of:
* **develop** - Main Branch containing the latest code. This is the main branch you will make changes to.
* **master** - Branch containing the latest stable code. DO NOT MAKE CHANGES TO THIS BRANCH.
* **release/vX.X.X** - Named branches containing code specific to a release. Only make changes to this branch if you are fixing a bug on a release branch.
#### Milestones, Issues, Tasks
The Milestones, issues, and tasks can be used to organize specific features or research projects. In general, there is a heirarchy:
* milestones (Big picture, "Epic"): contains many issues, organized by release.
* issues (Specific features / bugs, "Story"): may contain a list of tasks; represent
* task list (to do list, "Tasks"): list of steps required to close an issue, e.g.:
----------------------------------
* [ ] first do this
* [ ] then this
* [ ] completed when x and y
----------------------------------
#### Editing files on GitHub
The **easiest** approach is to use GitHub's browser based workflow. This is useful when your change is a few lines, if you are editing a wiki, or if the edit is trivial (and won't break the code). The [GitHub documentation is here](https://help.github.com/articles/github-flow-in-the-browser) but it is simple: finding the page or file you want to edit, click "edit" and then the GitHub web application will automatically forking and branch, then allow you to submit a pull request. However, it should be noted that unless you are a member of the PEcAn project that the "edit" button will not be active and you'll want to follow the workflow described below for forking and then submitting a pull request.
### Recommended Git Workflow
Summary: development should occur on a fork of the main repository.
1. Fork
2. Create Branch
3. Develop
4. Push changes to your fork
5. Create pull request from branch on your fork to develop branch on pecanproject/pecan
**Each feature should be in its own branch** (for example each issue is a branch, names of branches are often the issue in a bug tracking system).
**Commit and Push Frequency** On your branch, commit any time that you have done work that you do not want to re-do. Remember, pushing changes to your branch is like saving a draft. Submit a pull request when you are done.
#### Before any work is done
The first step below only needs to be done once when you first start working on the PEcAn code. The steps below that need to be done to set up PEcAn on your computer, and would need to be repeated if you move to a new computer.
All contributors should create a fork of the PEcAn source code in their own folder see [github help: "fork a repo"](https://help.github.com/articles/fork-a-repo)). This forked repository will allow you to create branches and submit these changes back to GitHub using pull requests to the develop branch of PEcAn.
The pull request will start a review process that will eventually result in the code being merged into the main copy of the codebase. See https://help.github.com/articles/fork-a-repo for more information, especially on how to keep your fork up to date with respect to the original. (Rstudio users should also see [Git + Rstudio](Using-Git.md#git--rstudio), below).
You can setup SSH keys to make it easier to commit cod back to GitHub. This might especially be true if you are working from a cluster, see [set up ssh keys](https://help.github.com/articles/generating-ssh-keys)
There is a script in the scripts folder called `scripts/syncgit.sh` that will keep your fork in sync with the main pecanproject repository.
1. Introduce yourself to GIT
```sh
git config --global user.name "FULLNAME"
git config --global user.email [email protected]
```
2. Fork PEcAn on GitHub. Go to the PEcAn source code and click on the Fork button in the upper right. This will create a copy of PEcAn in your personal space.
3. Clone to your local machine via command line
```sh
git clone [email protected]:<username>/pecan.git
```
4. Define `PEcAnProject/pecan` as upstream repository
```sh
cd pecan
git remote add upstream [email protected]:PecanProject/pecan.git
```
##### Hint: Keeping your fork in sync
If you have used the instructions above, you can use the helper script called [`scripts/syncgit.sh`](https://github.com/PecanProject/pecan/blob/master/scripts/syncgit.sh) to keep the master and develop branches of your own fork in sync with the PEcAnProject/pecan repository.
After following the above, your .git/config file will include the following:
```
...
[remote "origin"]
url = [email protected]:<username>/pecan.git
fetch = +refs/heads/*:refs/remotes/origin/*
[branch "develop"]
remote = origin
merge = refs/heads/develop
[remote "upstream"]
url = [email protected]:PecanProject/pecan.git
fetch = +refs/heads/*:refs/remotes/upstream/*
```
Then, you can run:
```sh
./scripts/syncgit.sh
```
Now the master and develop branches on your fork will be up to date.
#### Using Branching
Ideally, a developer should create a new branch for each feature or bug fix
1. Make sure you start in the develop branch
```sh
git checkout develop
```
2. Make sure develop is up to date
```sh
git pull upstream develop
```
3. Run the PEcAn MAKEFILE to compile code from the main directory.
```sh
make
```
4. Create a new branch and switch to it
```sh
git checkout -b <branchname>
```
5. Work/commit/etc
```sh
git add <file_that_was_changed.R>
git commit -m "<some descriptive information about what was done>"
```
6. Make sure that code compiles and documentation updated. The make document command will run roxygenise.
```sh
make document
make
```
7. Push this branch to your github space
```sh
git push origin <branchname>
```
8. submit pull request with [[link commits to issues|Using-Git#link-commits-to-issuess]];
* also see [github documentation](https://help.github.com/articles/using-pull-requests)
#### After pull request is merged
1. Make sure you start in master
```sh
git checkout develop`
```
2. delete branch remotely
```sh
git push origin --delete <branchname>`
```
3. delete branch locally
```sh
git branch -D <branchname>`
```
#### Link commits to issues
You can reference and close issues from comments, pull requests, and commit messages. This should be done when you commit code that is related to or will close/fix an existing issue.
There are two ways to do this. One easy way is to include the following text in your commit message:
* [**Github**](https://github.com/blog/1386-closing-issues-via-commit-messages)
* to close: "closes gh-xxx" (or syn. close, closed, fixes, fix, fixed)
* to reference: just the issue number (e.g. "gh-xxx")
### Useful Git tools
#### GitHub Desktop
The easiest way to get working with GitHub is by installing the GitHub
client. For instructions for your specific OS and download of the
GitHub client, see https://help.github.com/articles/set-up-git.
This will help you set up an SSH key to push code back to GitHub. To
check out a project you do not need to have an ssh key and you can use
the https or git url to check out the code.
#### Git + Rstudio
Rstudio is nicely integrated with many development tools, including git and GitHub.
It is quite easy to check out source code from within the Rstudio program or browser.
The Rstudio documentation includes useful overviews of [version control](http://www.rstudio.com/ide/docs/version_control/overview)
and [R package development](http://www.rstudio.com/ide/docs/packages/overview).
Once you have git installed on your computer (see the [Rstudio version control](http://www.rstudio.com/ide/docs/version_control/overview) documentation for instructions), you can use the following steps to install the PEcAn source code in Rstudio.
### Advanced
#### Fixing a release Branch
If you would like to make changes to a release branch, you must follow a different workflow, as the release branch will not contain the latest code on develop and must remain seperate.
1. Fetch upstream remote branches
`git fetch upstream`
2. Checkout the correct release branch
`git checkout -b release/vX.Y.Z`
4. Compile Code with make
`make`
5. Make changes and commit them
`git add <changed_file.R>`
`git commit -m "Describe changes"`
6. Compile and make roxygen changes
`make`
`make document`
7. Commit and push any files that were changed by make document
8. Make a pull request. It is essential that you compare your pull request to the remote release branch, NOT the develop branch.
#### Tags
Git supports two types of tags: lightweight and annotated. For more information see the [Tagging Chapter in the Git documentation](http://git-scm.com/book/ch2-6.html).
Lightweight tags are useful, but here we discuss the annotated tags that are used for marking stable versions, major releases, and versions associated with published results.
The basic command is `git tag`. The `-a` flag means 'annotated' and `-m` is used before a message. Here is an example:
`git tag -a v0.6 -m "stable version with foo and bar features, used in the foobar publication by Bob"`
Adding a tag to the a remote repository must be done explicitly with a push, e.g.
`git push v0.6`
To use a tagged version, just checkout:
`git checkout v0.6`
To tag an earlier commit, just append the commit SHA to the command, e.g.
`git tag -a v0.99 -m "last version before 1.0" 9fceb02`
### References
#### Git Documentation
* Scott Chacon, ‘Pro Git book’,
[http://git-scm.com/book](http://git-scm.com/book)
* GitHub help pages,
[https://help.github.com](https://help.github.com)/
* Main GIT page
[http://git-scm.com/documentation](http://git-scm.com/documentation)
* Another set of pages about branching,
[http://sandofsky.com/blog/git-workflow.html](http://sandofsky.com/blog/git-workflow.html)
* [Stackoverflow highest voted questions tagged "git"](http://stackoverflow.com/questions/tagged/git?sort=votes&pagesize=50)
#### GitHub Documentation
When in doubt, the first step is to click the "Help" button at the top of the page.
* [GitHub Flow](http://scottchacon.com/2011/08/31/github-flow.html) by
Scott Chacon (Git evangelist and Ruby developer working on GitHub.com)
* [GitHub FAQ](https://help.github.com/)
* [Using Pull Requests](https://help.github.com/articles/using-pull-requests)
* [SSH Keys](https://help.github.com/articles/generating-ssh-keys)