Examples of collaborative workflows
24 January 2025
Background
This document demonstrates some of the workflows we saw in class here. All of these workflows have some pros and cons. It’s up to you and your team as to which one you adopt. Also note that your preferences might change, depending on the composition of your team and the task at hand.
Centralized workflow
A centralized workflow uses a single repo for all changes to the project. All team members pull from and push to the same repo.
Imagine Juan sits down to work on his new testing project that Mary and Aisha have been working on as well. The first thing Juan does is pull from the remote repository.
Everything is up to date, so Juan works on the R script for doing some simple math operations. He adds 2 lines to the script to demonstrate a subtraction operation, and then saves his changes.
After basking in the glow of his wonderful new code, Juan decides he should take a break for awhile, so he commits his changes.
The last step before Juan takes a break is to push his local commit up to the shared repo on GitHub.
Oops–that did not go as expected!
What went wrong? Git is telling us that there are some changes on the remote repo that Juan does not have in his local copy. How did that happen? It turns out that Mary was also working on the project at the same time as Juan. In between the time that Juan sat down and pulled the changes from the remote repo (there were none at the time), Mary made some changes to the script, committed them, and pushed them to the remote repo. In looking at the error message from Git, Juan notices that it suggests he should pull the changes and integrate them into his own script.
Juan goes ahead and pulls Mary’s recent changes to his local repo,
which issues another warning about a so-called merge conflict
in R/00_testing.R that Juan will have to fix.
Merge conflicts
When Juan inspects his version of 00_testing.R he sees
that Git has added some information to the script, which brackets the
new changes that both Juan and Mary made:
<<<<<<< HEAD
## subtraction
num - den
=======
## addition
num + demo
>>>>>>> d1ab55e3cf1979efd0a61954305f742cfbb38e11
You can think of these new lines as “conflict dividers”.
The ======= line is the center of the conflict.
Everything between <<<<<<< HEAD and
======= is content that exists in the local repo
to which the HEAD ref is pointing.
Everything between ======= and
>>>>>>> d1ab55e3cf1979efd0a61954305f742cfbb38e11
is content that is present in the remote repo.
At this point, it would be a good idea for Juan to contact Mary and find out what her plans are, so he can avoid this problem in the future.
After confirming that Mary is done making changes for awhile, Juan can return to resolving the current merge conflict. To do so, Juan inspects the new changes that Mary made and decides if he wants to merge them into his version of the file, or whether he wants to discard them. In this case, Juan is happy with the new addition operation that Mary made, so he accepts them by simply deleting the conflict dividers.
Now Juan can commit his resolved changes and push them to the remote repo.
Now Juan is all set on his side, but Mary should make sure that she pulls Juan’s changes to her local repo before she starts working on the script again.
This scenario does not necessarily require two or more collaborators.
For example, Mark knows from personal experience that someone can do some work on a computer in their office, commit those changes, and then forget to push them before heading home. Upon arriving home, they could pull their changes to their laptop, make additional changes, commit them, and then push them to the remote repo. Upon returning back to the office, they can encounter problems with committing and pushing those changes they forgot about the day before.
Feature branch workflow
The feature branch workflow is designed around multiple branches within a repo. These branches can contain copies of files on the main branch, and are typically used for the development of specific features.
Create a branch
Let’s look at two different ways to create a new branch.
Review these instructions for creating a new branch from within GitHub, but don’t follow through with them. We’ll instead use the second approach shown below.
The first approach is from GitHub itself. To do so, navigate to the remote repo and click on the button marked main in the upper left. This will open a dialogue box with a line for you to find or create a branch. Type the name of the new branch (e.g., “develop”) and then hit “return”.
The second option for creating a new branch, which we’ll follow here, is to do so from within RStudio.
Click on the purple button with 2 rectangles and a diamond in the Git pane, which will bring up a dialogue window where you can enter the name of your new branch (we’ll call it “develop”). Press the Create button when you’re done.
At this point, you’ll see a message window from Git with the following information:
- lines 1-2: Git created a new branch and switched over to it with
git checkout -B develop - lines 3-10: Git pushed all of your local files to a newly created
developbranch on the remote GitHub repo.
Git is also suggesting you create a so-called pull request to move changes from the develop branch into the main branch by navigating to your remote repo on GitHub.
If you navigate back to the testing repo on GitHub and refresh your browser, you will see that there are now 2 branches there: main and develop.
Let’s go ahead and make a small change to our R test script (note that the following assumes you have not already made these changes in the above section on Centralized workflow). After doing so, we’ll commit and push the changes on the develop branch up to our remote repo on GitHub.
Add the following 2 lines of code to the 00_testing.R
script. Save the changes when you are finished.
Add the file to staging and commit it. Include a short but informative commit message and click the Commit button when ready.
Click on the green uparrow next to “Push” to push your changes to GitHub.
RStudio will pop open a window echoing your push command and the destination.
Pull requests
Now let’s take the advice we received earlier about creating a “pull request” (or “PR” for short). You can think of a pull request as an offer of support. In effect, someone who submits a pull request is kindly requesting that the repo owner pull new changes into their repo.
Navigate to your testing repo on GitHub.
Upon arriving there, we see a message that “develop had recent pushes less than a minute ago”. To the right of that is a green button marked Compare & pull request.
Click on the green Compare & pull request button, which will take you to a page to open a pull request.
At the top you will see some information about the branches from which and to where the changes will be merged, along with a note about the branches being okay to merge. If you scroll down the page, you’ll see the changes that were committed, when they were made, and who did it.
If your pull request involves multiple files, features, etc, it’s a good idea to include some additional information in the comment box (this can include Markdown flavored text).
Click on the green Create pull request button, which will take you to another page where you can review any comments (here there are none) and merge the pull request.
In the middle of the page, you’ll see a note about This branch has no conflicts with the base branch and a green button labeled Merge pull request.
Go ahead and push that button.
At this point, the window will switch over to asking you to confirm the merge.
Go ahead and click on the green Confirm merge button.
After doing so, GitHub will now report Pull request successfully merged and closed (you’ll also notice that the green Open oval below the name of the pull request has changed to a purple Merged oval). GitHub also tells you that “You’re all set–the develop branch can be safely deleted.”
