8.2 Git and GitHub Workflow

Using Git

8.2.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].

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

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

8.2.1.2 PEcAn Project and Github

These instructions apply to other repositories too.

8.2.1.3 PEcAn Project Branches

We follow branch organization laid out on this page.

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.
  • main - 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.

8.2.1.4 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

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

8.2.3 Useful Git tools

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

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

8.2.4 Advanced

8.2.4.1 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

  1. Checkout the correct release branch

git checkout -b release/vX.Y.Z

  1. Compile Code with make

make

  1. Make changes and commit them

git add <changed_file.R> git commit -m "Describe changes"

  1. Compile and make roxygen changes make make document

  2. Commit and push any files that were changed by make document

  3. Make a pull request. It is essential that you compare your pull request to the remote release branch, NOT the develop branch.

8.2.4.2 Tags

Git supports two types of tags: lightweight and annotated. For more information see the Tagging Chapter in the Git documentation.

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

8.2.5 References

8.2.5.1 Git Documentation

8.2.5.2 GitHub Documentation

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

8.2.6 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

8.2.6.1 Bugs, Issues, Features, etc.

8.2.6.2 Reporting a bug

  1. (For developers) work through debugging.
  2. Once you have identified a problem, that you can not resolve, you can write a bug report
  3. Write a bug report
  4. submit the bug report
  5. If you do find the answer, explain the resolution (in the issue) and close the issue

8.2.6.3 Required content

Note:

  • a bug is only a bug if it is reproducible
  • clear bug reports save time
  1. Clear, specific title
  2. 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
  1. 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)

8.2.6.4 Requesting a feature

(from The Pragmatic Programmer, available as ebook 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:

  1. Bob is at www.mysite.edu/maps
  2. map of the the region (based on user location, e.g. US, Asia, etc)
  3. option to “use current location” is provided, if clicked, map zooms in to, e.g. state or county level
  4. for site run:
    1. option to select existing site or specify point by lat/lon
    2. option to specify a bounding box and grid resolution in either lat/lon or polar stereographic.
  5. 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.

8.2.6.5 Closing an issue

  1. Definition of “Done”
  • test
  • documentation
  1. when issue is resolved:
  • status is changed to “resolved”
  • assignee is changed to original author
  1. if original author agrees that issue has been resolved
  • original author changes status to “closed”
  1. except for trivial issues, issues are only closed by the author

8.2.6.6 When to submit an issue?

Ideally, non-trivial code changes will be linked to an issue and a commit.

This requires creating issues for each task, making small commits, and referencing the issue within your commit message. Issues can be created on GitHub. These issues can be linked to commits by adding text such as fixes gh-5).

Rationale: This workflow is a small upfront investment that reduces error and time spent re-creating and debugging errors. Associating issues and commits, makes it easier to identify why a change was made, and potential bugs that could arise when the code is changed. In addition, knowing which issue you are working on clarifies the scope and objectives of your current task.