Project workflow - rlsweeney/Sweeney_RA_Manual GitHub Wiki

Branch - Commit - Pull Request workflow

• At any given point in time, the master branch contains stable versions of the files we want to keep.
• When we make changes, we want to create a separate branch to work in before integrating the changes into master.
• Branches should be "issue" focused - [However, you can also make branches to play around with some files (for example I might have a branch called rs_scratch)]
  • Typically we will have issues describing specific tasks, like read in data or run some regressions.
  • Imagine we have an issue (#10) to read in some data from the EIA. You might create a branch called issue10_clean-eia-data.
  • You would make a clone off of master (I find it easiest to do this on GitHub), and pull it to your local copy of the repo.
  • You would then work in this branch locally, committing as you see fit and syncing changes to this branch.
• Once you're happy with the changes (typically when the issue is complete), submit a pull request.
  • You can do this by pushing your local changes to the branch, then clicking on "Create Pull Request" on GitHub.
  • Be sure to clearly document the major changes in the comments section here.
• I will review them, resolve differences, and integrate into master.
  • Sometimes I will make comments on your pull request, which you would address in your branch. Once you push your changes, the pull request will automatically update on GitHub.
• More info on this "branch-commit-pull request" workflow here
• One important thing to remember: With few exceptions, you always want to create your branch off the master branch. This facilitates merging later.

Using issues

• GitHub issues are where we'll create lists of things we need to do.
• These can contain to-do check boxes or general descriptions of tasks in flux.
• Ideally each task would map to an actionable set of steps that will culminate in a pull request.
• We can also use issues to store notes from meetings, model ideas, etc.