VERSION CONTROL PRACTICUM

The following set of problems are designed to expose you to version control in software development. Version control helps you:

• Track changes to your files over time.
• Revert to earlier versions when needed.
• Collaborate with others without overwriting each other's work.
• Experiment safely with new ideas in separate branches.

Version control is like a time machine for your code: you write some code today [version 1]; Tomorrow, you improve it [version 2]; A week later, something breaks, but you can go back in time to version 1 and compare or restore it.

Git is the most used version control software nowadays. There's also GitHub, a online platform to host Git repositories. Here's a table briefly describing the differences between the two:

---

Stage 0: Configurations

Before you begin, let's make sure you have the configuration needed to work with Git and GitHub.

• Create an account in github.com (if you don't have one already).
• Send me (via e-mail or Teams) your GitHub username so I can invite you to collaborate in the repository. After you are invited, check the email inbox associated with your GitHub account to accept the invitation.
• Now, you need to setup authentication procedures in order to git push your local changes to the repository in GitHub. To set up authentication procedures, please follow the guide below:
  • Install GitHub CLI for macOS, Windows or Linux.
  • After a successful installation, in the command line, enter gh auth login, then follow the prompts:
    • When prompted for your preferred protocol for Git operations, select HTTPS.
    • When asked if you would like to authenticate to Git with your GitHub credentials, enter Y.
    • Choose the option Login with a web browser, and copy the code you are given (you will needed in the next step).
  • You will be directed to github.com to authenticate using your GitHub credentials (plus that code you copied).

If everything went well, you are ready to begin. If you get stuck, ask for help or troubleshoot with your classmates.

---

Stage 1: Basic Git Workflow

Goal: Clone a repository from GitHub, make a change, and push it.
Problem: You found a repository on GitHub that you want to collaborate by adding your own changes to some files and creating new ones. You have already requested to be added to the repository as a collaborator.

---

1. Open a terminal/command prompt and clone the repository
   git clone https://github.com/svargasperez/COMP305practicum.git
cd COMP305practicum
   git clone downloads a copy of the repository COMP305practicum.git and places it in the directory COMP305practicum.
   
   
2. Create a new file
   echo "Hello from [yourname]" > your_name.txt
   - What are these commands exactly doing?
   
   
3. Stage the file
   git add your_name.txt
   git add adds a file (or files) to the staging area, which is another file, generally contained in your Git directory, that stores information about what will go into your next commit. If you type git add ., then git will add all the files you've modified to the staging area.
   
   
4. Commit the file
   git commit -m "Adding your_name.txt to the repo"
   git commit makes your staged content into a new commit snapshot. The -m flag is use to add a message describing the commit.
   
   
5. Push to the main branch
   git push
   git push transmits your local branch commits to the remote repository branch (in our case COMP305practicum.git in GitHub)
   
   

---

Stage 2: Branching and Merging

Goal: Learn how to work on feature branches and merge changes back.
Problem: You want to experiment with a piece of code for the project, but you don't want to mess with the main branch of the repository, so you create a "feature branch" to experiment. After you deem the process a great success, you merge your feature branch with main.

---

1. Create a new branch
   git checkout -b feature-[yourname]
   git checkout switches to a different branch. By providing the -b flag, the branch feature-[yourname] is created first and then switched to. This is equivalent to:
   git branch feature-[yourname]
git checkout feature-[yourname]
   You can also use the command git branch (without a branch name) to list all the available branches (inlcuding main)
   
   
2. Make a change in the new branch
   echo "This is my feature branch" > feature_yourname.txt
git add feature_yourname.txt
git commit -m "Add feature_yourname.txt in my branch"
3. Push the branch to GitHub
   git push origin feature-[yourname]
   This command uploads your new branch and its commits from your local computer to the remote repository in GitHub.
   
   
4. Switch back to main and merge
   git checkout main
git pull # ensure you're up to date
git merge feature-[yourname]
   The git pull command updates your local main branch with the latest changes from GitHub. By issuing this command, you make sure you have the most recent version of main and don't accidentally merge into an outdated branch. git merge tells Git to take the changes you made in feature-[yourname] and apply them to main.
   
   
5. Push the merged changes
   git push

---

Stage 3: Merge Conflicts

Goal: Simulate and resolve a merge conflict.
Problem: You and your fellow programming partner(s) made changes to the same file in your own branches. At the time you wanted to merge your changes, a conflict arises. You attempt to resolve it by taking a look at the conflicting file and manually editing it to incorporate all the changes to the file including yours.

---

1. Switch to the local branch you created on Stage 2
   git checkout feature-[yourname]
2. The whole class will edit the same line of the shared file conflicts.md on your local feature branch. For example, you will open the file and edit the line "- Line edited by Dr. Vargas-Pérez":
   ## Each student will edit the same line below by appending your name to the message like this:
*Line edited by Dr. Vargas-Pérez, Raja, and Sasha.*

- Line edited by Dr. Vargas-Pérez, and [Your Name].
   Save your changes.
   
   
3. You will commit, push, and merge your changes.
   git add conflicts.md
git commit -m "Adding my line to the shared file"
git push origin feature-[yourname]
git checkout main
git pull
git merge feature-[yourname]

   The first classmate that merges will succeed. The next one (might be you) will get a conflict.

Conflict Resolution Instructions

1. Git will pause the merge and show the conflict markers when you open the conflicting file:
   <<<<<<< HEAD
- Line edited by Dr. Vargas-Pérez, and Sasha.
=======
- Line edited by Dr. Vargas-Pérez, and Raja.
>>>>>>> feature-[yourname]

   The conflict message will look different for each one of you, but the example code shows the general idea.

2. Edit the file to manually resolve the conflict:
   - Line edited by Dr. Vargas-Pérez, Raja, and Sasha.
   In a real world scenario, you need to decide:

   [...] if you want to keep only your branch's changes, keep only the other branch's changes, or make a brand new change, which may incorporate changes from both branches. Delete the conflict markers <<<<<<<, =======, >>>>>>> and make the changes you want in the final merge.

   In our example, you incorporated both changes into the final merge. Save your changes.
   
   
3. Add and commit the resolution:
   git add conflicts.md
git commit -m "Resolving merge conflict"
4. Push the result:
   git push

---

Wrap-Up Discussion

When you are done with this activity, reflect:

• What did you notice when working on the same file?
• How can we avoid conflicts when working with version controlled files?
• What are pros/cons of merging early vs late?
• What's the difference between merge and rebase?

You do not need to submit the answers to these questions, but they will help your bi-weekly reflection and your future work with the final project.

---

Evaluation

This practicum is worth 5 points. The following rubrics describe the criteria I will use to evaluate your work:

• Stage 0 - Configurations
  • Your computer allows you to authenticate to GitHub via the CLI. 0.5 pts.
• Stage 1 - Basic Git Workflow
  • A file (your_name.txt or similar) was successfully pushed into the GitHub repository. 1 pt.
• Stage 2 - Branching and Merging
  • A file (feature_yourname.txt or similar) was successfully pushed into the GitHub repository after merging your local feature branch. 1.5 pts.
• Stage 3 - Merge Conflicts
  • The file conflicts.md contains your name in the line you were instructed to modify. 2 pts.