-
Notifications
You must be signed in to change notification settings - Fork 0
Using Git and GitHub
The EDUCE material is mainly provided as R Markdown files, i.e., code rendered as documents. It is widespread to develop code while using a version control system. A version control system allows you to save a version of your code (which might be spread across many files), keep a history of your code changes, go back in time to previous versions or undo any unintentional changes. One of the most common version control systems is Git and it is used for all EDUCE projects.
When collaborating with other people on code, it is necessary to sync changes across multiple computers. One service to facilitate syncing of code across many machines is GitHub. Think of it as a file sharing and syncing services like Dropbox or Google Drive. At the same time, GitHub also provides many social features to track the progress of a project, discuss changes, assign tasks and much more.
Any project you track with Git on your computer is called a repository or repo for short. If this project is also synced to GitHub, this remote copy is referred to as the remote. Any version you save with Git is called a commit. When you sync changes from your local repo to a remote, you push changes/commits, or when you download changes on the remote to your local repo, you pull changes/commits.
Here is a short overview if you want to learn more about Git and GitHub.
Learning to work with Git and GitHub can be initially challenging for multiple reasons. As you can see above, using these tools involves a lot of jargon. A lot of documentation you will find typically involves using the command line, i.e. text-based commands issued in a program called terminal instead of using a graphical user interface.
Check out our chapters on Git and GitHub of our Reproducible research workshop or attend it when available. This software carpentry tutorial is a great place to start with many exercises. Happy Git and GitHub for the useR also provides an excellent entry point to Git and GitHub, particularly from an R perspective.
There are many GUIs such as the official GitHub Desktop app. RStudio also provides Git/GitHub integration. They are an excellent point to start but often do not offer the more advanced operations of Git in the command-line tool.
As an EDUCE-UBC collaborator or member, you will clone our remotes to your computer (do NOT fork it) and push your commits directly to them:
git clone <remote address>
We follow these conventions for committing message subject lines. Good subject lines are essential for collaborations, so review them carefully as you write them yourself or see them during code review and provide feedback.
As you develop your code, you might work on one or more issues. If your commit addresses a specific issue, link them by adding instructions in your commit footer as described here.
We develop new content by following the GitHub Flow model. In this workflow, there is a branch called main that will at all times represent a working version of our content. When you start on new content in your local repo, you will be given a branch name to work on or create and switch to a new branch named <feature-name>. Use a dash - for spaces in the branch name:
git checkout -b <feature-name>
After you have finished working on a branch and the content is ready to be merged to main, you will issue a pull request, i.e. other members of EDUCE will do a code review, give feedback, or approve your request to merge. You can also use the pull request to ask for help with a problem, i.e. in the end, the branch won't be merged, but someone can look at your code and provide input.
When processing your code review changes, make use of applying multiple suggestions in a single commit.