Summary:

This document describes the steps required to download PEcAn, make changes to code, and submit your changes.

For asking questions, reporting bugs, and requesting features, see our documentation for reporting issues on Redmine and GitHub
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 References section at the the bottom of this page.
To make trivial changes, see Quick and Easy
To make changes to the code, start with the basic workflow.
If you want to submit changes that you've made to be part of PEcAn you'll want to follow Committing Changes Using Pull Requests

To update your local branch

cd pecan
git pull upstream master
./scripts/build.sh

GIT and GitHub Overview

Git

Git is a version control software; GitHub is a project-hosting website that is similar to Redmine but easier to use for open and collaborative development.

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. In addition, there are three fun tutorials for learning git:

Learn Git is a great web-based interactive tutorial.
LearnGitBranching
TryGit.

For additional tutorials and background see References

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.

PEcAnProject on GitHub: https://github.com/organizations/PecanProject

PEcAn source code:
- https://github.com/PecanProject/pecan.git
- git@github.com:PecanProject/pecan.git
BETYdb source code:
- https://github.com/PecanProject/bety.git
- git@github.com:PecanProject/bety.git
These instructions apply to other repositories too.

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
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
```

Quick and Easy

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 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

Each feature should be in it’s own branch (for example each redmine issue is a branch, names of branches are often the issue in a bug tracking system).

Commit and Push Frequency On your branch, commit at minimum once a day before you push changes: even better: every time you reach a stopping point and move to a new issue. best: 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. If you are working from the PEcAn VM, you can skip the "git clone" since the PEcAn code is already installed.

Most people will not be able to work in the PEcAn repository directly and will need to create a fork of the PEcAn source code in their own folder. To fork PEcAn into your own github space (github help: "fork a repo"). This forked repository will allow you to create branches and commit changes back to GitHub and create pull requests to the master of PEcAn.

The forked repository is the only way for external people to commit code back to PEcAn and BETY. 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, 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

Introduce yourself to GIT

 git config --global user.name "FULLNAME"
 git config --global user.email you@yourdomain.example.com

Fork PEcAn on GitHub. Goto 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.

Clone to your local machine

 git clone git@github.com:<username>/pecan.git

Define upstream repository

 cd pecan
 git remote add upstream git@github.com:PecanProject/pecan.git

During development:

commit often;
each commit can address 0 or 1 issue; many commits can reference an issue (see [[Link commits to issue|Using-Git#link-commits-to-issues]])
ensure that all tests are passing before anything is pushed into master.

Basic Workflow

PLEASE DO NOT USE THIS, SEE ADVANCED WORKFLOW!

Get the latest code from the main repository
```
 git pull upstream master
```
Do some coding

Commit after each chunk of code (multiple times a day)

 git commit -m "<some descriptive information about what was done; references/fixes gh-X>"

Push to YOUR Github (when a feature is working, a set of bugs are fixed, or you need to share progress with others)
```
 git push origin <branchname>
```
Before submitting code back to the main repository, make sure that code compiles
```
 ./scripts/build.sh -c
```
submit pull request with a reference to related issue (see [[Link commits to issue|Using-Git#link-commits-to-issues]]);
- also see github documentation

Advanced Workflow: A new branch for each change

Make sure you start in master
```
 git checkout master
```
Make sure master is up to date
```
 git pull upstream master
```
Run any tests / make sure that code compiles
For PEcAn: Build most recent versions of R packages (./scripts/build.sh -h for help))
```
  ./scripts/build.sh
```
For BETYdb (see BETY wiki)
```
  rspec
```
Create a branch and switch to it
```
 git checkout -b <branchname>
```

work/commit/etc

 git commit -m "<some descriptive information about what was done>"

Run any tests / make sure that code compiles

For PEcAn: ./scripts/build.sh -c

Push this branch to your github space
```
 git push origin <branchname>
```
submit pull request with [[link commits to issues|Using-Git#link-commits-to-issuess]];
- also see explanation in this PecanProject/bety issue and github documentation

After pull request is merged

Make sure you start in master
```
 git checkout master
```
delete branch remotely
```
 git push origin --delete <branchname>
```
delete branch locally
```
 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
- to close: "closes gh-xxx" (or syn. close, closed, fixes, fix, fixed)
- to reference: just the issue number (e.g. "gh-xxx")
- avoid "closes #xxx" which will cross-reference Redmine issues
Redmine:
- to close: "fixes redmine #xxx" (or closes etc.)
- to reference: "redmine #xxx"
Bitbucket:
- to close: reference and use web interface!
- to reference: "re #xxx"

Another way is to just add the url to the issue that you are updating. For example, if you are resolving an issue in Redmine, you can simply write the text "resolved by pull request https://github.com/PecanProject/pecan/pull/1" in the comments.

For PEcAn

./scripts/build.sh -c

Committing Changes Using Pull Requests

GitHub provides a useful overview of how to submit changes to a project, Using Pull Requests.

Once you have added a feature on your local fork of the project that you would like to contribute, these are the steps:

Submit a Pull Request
Pull request is reviewed by a member of the PEcAn core group
Any comments should be addressed
Additional commits are added to the pull request
When ready, changes are merged

Other Useful Git Commands:

GIT encourages branching "early and often"

First pull from master
Branch before working on feature
One branch per feature
You can switch easily between branches

Merge feature into main line when branch done

    git branch <name of branch>
    git checkout <name of branch>
    repeat 
      write some code
      commit
    until done

    git checkout master
    git merge <name of brach>
    git push

If during above process you want to work on something else, commit all your code, create a new branch, and work on new branch.

Delete a branch: git branch -d <name of branch>
To push a branch git: push -u origin`

To check out a branch:

git fetch origin
git checkout --track origin/<name of branch>

Get the remote repository locally:
```
  git clone URL
```
To update local repository to latest:
```
  git pull
```
To add new files to the local repository:
```
  git add <file>
```
To commit changes
```
  git commit <file|folder>
```
To update remote repository:
```
  git push
```
Show graph of commits:
```
  git log --graph --oneline --all
```

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 and R package development.

Once you have git installed on your computer (see the Rstudio version control documentation for instructions), you can use the following steps to install the PEcAn source code in Rstudio.

Creating a Read-only version:

This is a fast way to clone the repository that does not support contributing new changes (this can be done with further modification).

install Rstudio (www.rstudio.com)
click (upper right) project
- create project
- version control
- Git - clone a project from a Git Repository
- paste https://www.github.com/PecanProject/pecan
- choose working dir. for repo

For development:

create account on github
create a fork of the PEcAn repository to your own account https://www.github.com/pecanproject/pecan
install Rstudio (www.rstudio.com)
generate an ssh key
- in Rstudio:
- Tools -> Options -> Git/SVN -> "create RSA key"
- View public key -> ctrl+C to copy
- in GitHub
- go to ssh settings
- -> 'add ssh key' -> ctrl+V to paste -> 'add key'
Create project in Rstudio
- project (upper right) -> create project -> version control -> Git - clone a project from a Git Repository
- paste repository url git@github.com:<username>/pecan.git>
- choose working dir. for repository

References:

Git Documentation

Scott Chacon, ‘Pro Git book’, http://git-scm.com/book
GitHub help pages, https://help.github.com/
Main GIT page, http://git-scm.com/documentation
Information about branches, http://nvie.com/posts/a-successful-git-branching-model/
Another set of pages about branching, http://sandofsky.com/blog/git-workflow.html
Stackoverflow highest voted questions tagged "git"

GitHub Documentation

When in doubt, the first step is to click the "Help" button at the top of the page.

GitHub Flow by Scott Chacon (Git evangelist and Ruby developer working on GitHub.com)
GitHub FAQ
Using Pull Requests
SSH Keys

Using Github and Git