26 Git and GitHub Workflow
26.1 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 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:
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.
26.1.2 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.
26.1.3 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.
126.96.36.199 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|
26.1.4 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.
26.1.5 Recommended Git Workflow
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 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.
26.1.6 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 develop branch 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 email@example.com
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.
Clone to your local machine via command line
git clone firstname.lastname@example.org:<username>/pecan.git
If this does not work, try the https method
git clone https://github.com/PecanProject/pecan.git
- Define upstream repository
cd pecan git remote add upstream email@example.com:PecanProject/pecan.git
26.1.7 During development:
- commit often;
- each commit can address 0 or 1 issue; many commits can reference an issue
- ensure that all tests are passing before anything is pushed into develop.
26.1.8 Basic Workflow
This workflow is for educational purposes only. Please use the Recommended Workflow if you plan on contributing to PEcAn. This workflow does not include creating branches, a feature we would like you to use. 1. Get the latest code from the main repository
git pull upstream develop
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 develop
- Before submitting code back to the main repository, make sure that code compiles from the main directory.
- submit pull request with a reference to related issue;
- also see github documentation
26.1.9 Recommended Workflow: A new branch for each change
- Make sure you start in develop
git checkout develop
- Make sure develop is up to date
git pull upstream develop
- Run the PEcAn MAKEFILE to compile code from the main directory.
- Create a branch and switch to it
git checkout -b <branchname>
git add <file_that_was_changed.R>
git commit -m "<some descriptive information about what was done>"
- Make sure that code compiles and documentation updated. The make document command will run roxygenise.
- 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]];
188.8.131.52 After pull request is merged
- Make sure you start in master
git checkout develop
- delete branch remotely
git push origin --delete <branchname>
- delete branch locally
git branch -D <branchname>
184.108.40.206 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.
- Fetch upstream remote branches
git fetch upstream
- Checkout the correct release branch
git checkout -b release/vX.Y.Z
- Compile Code with make
- Make changes and commit them
git add <changed_file.R>
git commit -m "Describe changes"
Compile and make roxygen changes
Commit and push any files that were changed by make document
Make a pull request. It is essential that you compare your pull request to the remote release branch, NOT the develop branch.
220.127.116.11 Other Useful Git Commands:
- GIT encourages branching “early and often”
- First pull from develop
- Branch before working on feature
- One branch per feature
- You can switch easily between branches
- Merge feature into main line when branch done
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>
- Show graph of commits:
git log --graph --oneline --all
26.1.10 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.
18.104.22.168 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
26.1.11 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
- choose working dir. for repository
22.214.171.124 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
- Another set of pages about branching, http://sandofsky.com/blog/git-workflow.html
- Stackoverflow highest voted questions tagged “git”
26.2 GitHub use with PEcAn
In this section, development topics are introduced and discussed. PEcAn code lives within the If you are looking for an issue to work on, take a look through issues labled “good first issue”. To get started you will want to review
We use GitHub to track development.
To learn about GitHub, it is worth taking some time to read through the FAQ. When in doubt, the first step is to click the “Help” button at the top of the page.
- To address specific people, use a github feature called @mentions e.g. write @dlebauer, @robkooper, @mdietze, or @serbinsh … in the issue to alert the user as described in the GitHub documentation on notifications
26.2.1 Bugs, Issues, Features, etc.
126.96.36.199 Reporting a bug
- (For developers) work through debugging.
- Once you have identified a problem, that you can not resolve, you can write a bug report
- Write a bug report
- submit the bug report
- If you do find the answer, explain the resolution (in the issue) and close the issue
188.8.131.52 Required content
- a bug is only a bug if it is reproducible
- clear bug reports save time
- Clear, specific title
- Description -
- What you did
- What you expected to happen
- What actually happened
- What does work, under what conditions does it fail?
- Reproduction steps - minimum steps required to reproduce the bug
- additional materials that could help identify the cause:
- screen shots
- stack traces, logs, scripts, output
- specific code and data / settings / configuration files required to reproduce the bug
- environment (operating system, browser, hardware)
26.2.2 Requesting a feature
(from The Pragmatic Programmer, available as
through UI libraries, hardcopy on David’s bookshelf)
- focus on “user stories”, e.g. specific use cases
Be as specific as possible,
Here is an example:
- Bob is at www.mysite.edu/maps
- map of the the region (based on user location, e.g. US, Asia, etc)
- option to “use current location” is provided, if clicked, map zooms in to, e.g. state or county level
- for site run:
- option to select existing site or specify point by lat/lon
- option to specify a bounding box and grid resolution in either lat/lon or polar stereographic.
- asked to specify start and end times in terms of year, month, day, hour, minute. Time is recorded in UTC not local time, this should be indicated.
26.2.3 Closing an issue
- Definition of “Done”
- when issue is resolved:
- status is changed to “resolved”
- assignee is changed to original author
- if original author agrees that issue has been resolved
- original author changes status to “closed”
- except for trivial issues, issues are only closed by the author