🛣️ Week 09 - Using Git as a team

Lab Roadmap (90 min)

Author

Dr. Jon Cardoso-Silva

Published

11 March 2024

🎯 Learning Objectives

Today’s main point is to practice working as a group on a data science project using GitHub. In a little more detail, we will learn how to:

  • accepting a Pull Request and merging it into the main branch
  • creating a website using GitHub Pages
  • add tasks (issues) to a GitHub project board
  • assign tasks to team members
  • create a new branch for each task
  • creating a Pull Request for when a task is done

📋 Lab Tasks

Buckle up! There’s a lot of reading to do today.

Part 0: Export your chat logs (~ 3 min)

As part of the GENIAL project, we ask that you fill out the following form as soon as you come to the lab:

🎯 ACTION POINTS

  1. 🔗 CLICK HERE to export your chat log.

    Thanks for being GENIAL! 🎟️

👉 NOTE: You MUST complete the initial form.

If you really don’t want to participate in GENIAL, just answer ‘No’ to the Terms & Conditions question - your e-mail address will be deleted from GENIAL’s database the following week.

Part 1 - Understand the group project requirements (20-30 min)

Go through the action points below as a group, then signal to your class teacher when you are all done reading and discussing the requirements.

🎯 ACTION POINTS

  1. Sit together in your group. If you are not in a group, ask your class teacher to assign you to one.

  2. 📝 Read and take note of the project requirements. Go to Step 1 - Forming Groups page, read and discuss all the information on that page. This will help you understand what you need to produce by 23 May 2024, 5pm UK time.

    • Ask your class teacher if you have any questions.

    • Or post questions to the #help-assessments channel on Slack later.

  3. 📝 Understand the next steps

You will be working on a group project for the next few months, and you have until 23 May 2024, 5pm UK time to complete it. There will be no extensions for this project. Here are the main next steps for your project:

  • Week 09 (today):
    • Form groups
    • Create a GitHub repository for your project
    • Ensure your repository can produce a website
    • Learn how to use GitHub collaboratively
  • Week 10 (next week):
    • Update your website with a temporary plan for your project (think of this as a pitch presentation)
    • You will have 5 minutes to present, using your website only, which sources you are considering, explain what you want to do until May, and how you plan to do it
    • More details can be found on the Step 2: Prepare a pitch presentation (W10 lab) page
  • Week 11 (in two weeks):

🤚 Signal to your class teacher that you’re done reading requirements.

Part 2 - The ritual of a Pull Request review (30 min)

You are already familiar with the ritual of save file -> git status -> git add -> git commit -> git push. Now, we will introduce you to the Pull Request ritual. This is a crucial part of working with Git as a team.

🎯 ACTION POINTS

This has to be done as a group.

  1. You need a name for your group. Discuss and agree on a name. It can be anything you like, but it should be something you all like and agree on and are comfortable displaying in public. This is the name that will be displayed on your website.

  2. Join the Git repository for your group: Go to our Slack workspace’s #announcements channel. We don’t share the link publicly. It is a private repository for enrolled students only.

  3. Make sure your repository can produce a website. Go to Settings and scroll down to the GitHub Pages section. Ensure the Source is set to the main branch and the directory is set to /docs. If not, change it and click Save. Wait a few seconds and refresh the page. You should see a green box with a link to your website. Click on it and check that it works.

  4. Raise your hand and call your class teacher. This is a 👨🏻‍🏫 TEACHING MOMENT. Your class teacher will open your group’s repository on GitHub and create a Pull Request with a new file.

    • The Pull Request will appear on your repository’s Pull requests tab.
    • You will also get an ✉️ e-mail notification.
    • Note: the file will not be visible on your main branch until you accept the Pull Request.

  5. Together, read the Pull Request description and see if you need to do something before accepting it. If you need to do something, do it.

    💡 TIP: The following GitHub documentation page might be helpful to you: Reviewing proposed changes in a pull request

  6. Accept and Merge the Pull Request. Return to your repository’s main page to see that your main branch now has the new docs/index.md file!

  7. Go to the ‘Actions’ tab and see if the website is being built. After a few minutes, you should see a green tick next to the latest build. You will find the URL there. Click on it and check that it works.

💭 REFLECTION TIME: Do you fully understand what you’ve just done? This new Git ritual is extremely important for your project, and you can’t afford not to grasp it!

Part 3 - Your time to create a Pull Request (30 min)

🎯 ACTION POINTS

  1. Create a new Issue on your repository’s Issues tab. The title should be `👥 Add our names to the website’. The description should read:

    - [ ] Add a h2 heading called `Team Members` to the `docs/index.md` file.
- [ ] Add a bullet points list with our names under the `Team Members` heading with the following format:
    - `<Name> <Surname> (<GitHub username>) | BSc in <Mysterious Sciences>`

    The < and > should not be included in the final text! They just indicate these are placeholders for you to fill in.

  2. Split the tasks:

    • one of you will play the role of the assigned to the Issue (the person who will do the task)
    • someone else will play the role of reviewer (the person who will check the task)

  3. The assigned person should go to their terminal and create a new branch called add-team-members by running each of the following commands:

    git fetch
git checkout main
git pull
git checkout -b add-team-members

  4. The assigned person should now open the docs/index.md file in their text editor and add the required text. Save the file. (They can get help from the other team members. It’s not a race.)

  5. The assigned person should now go to their terminal and run the following commands:

    git add docs/index.md
git commit -m "Add team members"

    Now, this is the point where you would normally just run git push. BUT GitHub does not know about your new branch yet. So, you need to run the following command instead:

    git push --set-upstream origin add-team-members

    The next time you run it, you can just run git push.

  6. The assigned person should now go to their repository’s Pull requests tab and create a new Pull Request. The base branch should be main, and the compare branch should be add-team-members. The title should be 👥 Add our names to the website. Write a useful description similar to the one we did above. Click Create Pull Request and tag the reviewer.

  7. The person playing the role of reviewer should now check that they are happy with the changes. If they are, they should accept and merge the Pull Request. If they are not, they should add a comment to the Pull Request explaining what needs to be changed. The assigned person should then make the changes and push them to the same branch. The reviewer should then check again and accept and merge the Pull Request.

📚 Homework

Prepare for next week’s pitch presentation

🎯 ACTION POINTS

  1. Read the instructions about next week’s pitch presentation on the Step 2: Prepare a pitch presentation (W10 lab) page.

  2. Decide who is doing what and how much time and effort you can dedicate to the project as a group.

    • Note: you don’t need to prepare anything crazy for next week. You will be fine if you have a plan written down on your website. The main goal of next week is to sense whether your project is feasible and to get feedback from your class teacher and peers.

  3. Start thinking long-term. What tasks do you want to tackle in your group project until the end of the Winter Term and until May (Spring Term)? Write them down in the Issues tab of your repository.

    For example, here are a few templates for Issue titles:

    • ‘Create a new Jupyter Notebook to test how to scrape data from website ’
    • ‘Update our .gitignore file to avoid sharing credentials by accident’
    • ‘Define a coherent directory structure for our project’
    • ‘Update our website with a new section called “Our Project”’
    • ‘Make our website look nicer by adding something called a Jekyll theme’
    • ‘Learn about Quarto and see if we can use it for our project’

  4. Assign the tasks to you and your team members and add deadlines for yourselves in the description of each task.