DSCI 521 Group Lab: Collaborative slides

Build one slide deck together, and create (git) conflicts

See the assessment table on the home page for the weight, due date, and where to submit.

This is a group assignment

You find out who is in your group when the assignments are released at the start of the week.
You have lab time to work on it together.
It is submitted and graded as a group. One submission for the whole group, and everyone gets the same score.

If a group member is unresponsive, your first job is to sort it out within the group. If that does not work, tell your instructor by Thursday, while there is still time to do something about it.

What you are doing

This is the only group assignment in DSCI 521, and the only repository in the course that more than one person can write to. Your Milestone 2 repository is not touched here. You go back to it in Milestone 3.

You are in a group of 3 to 4. Together you build one (1) Quarto reveal.js slide deck that introduces your group to the class.

By the end of this lab your group has:

One shared repository with a Quarto presentation in it.
Four question slides, chosen by your group, with every member’s answer on the same slide.
One personal slide per member, titled with that member’s name and CWL.
A screenshot on each personal slide of a real merge conflict in a .qmd file.
The deck live on GitHub Pages, that URL in the repository’s About section, and a PDF export.

Exploring merge conflicts are the point of this assignment

What we are teaching is what happens when several people change the same file at the same time, and how you get out of it.

In this task, we do not expect you to try to avoid conflicts!: - Do not divide the work up to avoid each other. - Do not take turns. - Sit together in lab, open the same file, and type into it at once.

Your changes are supposed to collide, to make your life easier, the assignment is graded based on you completing all the steps, not on how the slide deck looks or the content.

The only new thing this week is merge conflicts

You have already done the rest in Weeks 1 and 2:

clone, commit, push, pull
build and render a Quarto document
publish to GitHub Pages

So this assignment does not spell those out again. It says what the finished thing looks like and leaves the how to you.

When you are stuck, go back to the lecture notes and the earlier milestones, read what your tools print at you, and talk to your group.

Your group and your repository

We have created your repository and added every member to it. Find it in the github.ubc.ca GitHub Enterprise organization.

Every member has write access to the one repository.
Do not fork it.
Do not create branches.
Make sure not clone it inside another Git repository, including your username.github.io folder.

The repository starts private, and changing that is your job

We create these repositories private. While it stays private, nobody outside your group can open the repository. That includes us.

Before the deadline, change the visibility so the teaching team can open both. The setting is in the repository’s Settings.

We do not change it for you.
We do not chase it.
A repository we cannot open is marked as missing.

Do it early. It also controls whether your GitHub Pages URL works for anyone but you.

How to tell whether you got the visibility right

Ask a classmate who is not in your group to open your repository and your slides URL.

Your own group members can see both whatever the setting is, so checking on each other proves nothing. Someone outside the group is in the same position we are in when we grade.

A 404 or a permission error means the setting is not right yet.

Read this before you start

A few things catch people every year:

A repository we cannot open is a repository we cannot grade. Changing the visibility is part of the assignment.
We grade the last commit timestamped before the deadline. Not the newest commit, and not what is on your laptop. Work has to be committed and pushed before the deadline.
The deck has to be live at its URL by the deadline. Pushing is not enough. GitHub takes a minute or two to build the site, so do not leave the last push to the last minute, as you might encounter errors you won’t be able to fix.
git pull origin main before you start typing, and again before you push.
Everyone needs to make their own commits. We look at the history. One person committing for the group costs everyone in the group their marks.

Your slides inherit the repository’s visibility. Once you open the repository up for grading, your group is no longer the only audience:

Everything you put about yourself is voluntary.
Anyone who can open the deck can screenshot it.
Someone other than you can change the visibility later.

Share what you are comfortable sharing, and no more.

Step 1: Agree on your four questions

As a group, pick four questions from this list. Everyone answers all four.

Where did you live before MDS, and what is one thing you miss about it?
What did you do before MDS: a degree, a job, or both?
What made you apply to MDS?
What is one thing you want to be able to do by the end of the program?
What is the best thing you have eaten in Vancouver so far?
What do you do when you are not in front of a computer?
What is a skill you have that has nothing to do with data science?
What is the first piece of code you ever wrote, and what did it do?
What has surprised you most about your first few weeks here?
What is one recommendation for the class: a book, an album, a film, a restaurant, a trail, anything?
What is your go-to move when you are completely stuck on a problem?

Keep it something everyone is comfortable answering in public. Keep your answers short, and tag each answer by the group member. All answers should fit on a single slide.

You do not have to answer anything personal

Answer at whatever depth you like, or answer as your interests rather than as yourself. If a question does not suit you, ask your group to pick a different one.

Step 2: Build the deck

Textbook:

One person sets this up, pushes it, and tells the group. Everyone else pulls before making any other changes.

The repository has to end up with:

A Quarto reveal.js presentation at the top level, with its source named index.qmd. Work out what GitHub Pages does with a file called index.html and you will see why we ask for that name.
A title slide with your group number and every member’s name.
One slide per chosen question, empty for now.
Whatever else the site needs to render and be served. You did this in Milestone 2.

Do not create the personal slides here yet. Each member adds their own in Step 5.

Two things to think about while you set it up:

Milestone 2 had you create a file that stops GitHub from running Jekyll over your site. Your slides need it too.
Reveal.js can build self-contained slides, so the rendered .html carries its own resources instead of needing a folder of generated files beside it. Lecture 4 covers how to turn it on.

You can set this up as a Quarto project

A single index.qmd is enough. You can also make it a Quarto project with a _quarto.yml and control where things render from there, the way Milestone 2 did.

Either is fine. The requirement is the slides URL, not the layout of the repository.

Step 3: Answer the questions, all at the same time

This is the part that creates the conflicts.

Each question gets one slide, and all of your answers go on that same slide. You do not each get your own question, and you do not each get your own slide.

A finished question slide looks like this:

## What made you apply to MDS?

- **Ada**: I was writing the same pandas script at work every month
  and wanted to know why it worked.
- **Grace**: A professor told me my statistics were fine and my code was not.
- **Alan**: I wanted to stop guessing and start measuring.
- **Katherine**: Someone showed me a map made out of a spreadsheet.

So:

Everyone opens index.qmd at the same time.
Everyone adds their own answer to all four question slides.
Everyone commits and pushes when they are done.

The first person to push succeeds. Everyone else is rejected, with a message mentioning fetch first or Updates were rejected. That is the point. Read what Git prints.

You do not need the whole group present

Conflicts need two edits to the same place, not four people.

If only some of your group is in lab, work with whoever is there. Two of you editing the same slide is enough.
You can also create a conflict with yourself, by editing the file on GitHub in your browser and editing the same line on your laptop. That is how it was demonstrated in class. The recipe is in Step 5.

Everyone still needs their own screenshot, so whoever is missing has to trigger their own conflict later.

If four answers do not fit on one slide

Four answers on one slide can overflow, and reveal.js runs the text off the bottom without warning you.

Reveal.js has a built-in option that shrinks the text on your slides. It is one line in the YAML header. Find it in the Quarto reveal.js documentation, under presentation size and appearance.

We are not naming the option on purpose. Finding a setting in the documentation is part of what you are learning.

Short answers are the other fix, and usually the better one.

Step 4: Resolve the conflict

Textbook: Git: History, Conflicts, and Ignores

This is the one part we do spell out. It is what you are here to learn.

Your push was rejected because GitHub has commits you do not. Pull, and Git tries to combine their index.qmd with yours. Where two people changed the same place, Git stops and hands you the decision. It does that by writing both versions into your file, fenced with markers:

<<<<<<< HEAD
- **Ada**: I was writing the same pandas script at work every month.
=======
- **Grace**: A professor told me my statistics were fine and my code was not.
>>>>>>> 3f9a1c2

Read that as three parts:

<<<<<<< HEAD to ======= is what you had.
======= to >>>>>>> 3f9a1c2 is what you pulled in.
3f9a1c2 is the commit the incoming version came from.

Screenshot this now

You need a screenshot of these markers for Step 5. Take it while it is on your screen.

Then:

Edit the file so it says what you want it to say. Here that usually means keeping both answers: delete the three marker lines, leave both bullets. Git does not know whether you want your line, their line, both, or something new. You decide.
Make sure no marker survives anywhere in the file. A leftover marker costs marks and breaks your render. grep is a fast way to check:
```
grep -n '<<<<<<<\|=======\|>>>>>>>' index.qmd
```
That should print nothing.
Commit the resolution and push. Git tells you a merge is in progress and what it wants next. Read it rather than guessing.

Expect to do this more than once. Four people and one file is not tidy.

If your pull merged cleanly

Git sometimes works out how to combine two people’s edits on its own. No conflict, no markers. That is normal. Git only stops when the changes overlap.

You still need a conflict to screenshot:

Agree with one other member to change the same line, for example the same bullet on the same question slide.
Push at the same time.

Two edits to one line is something Git will not decide for you. If your group has finished and you still have no screenshot, use the solo recipe in Step 5.

Step 5: Your own slide

Each member adds one slide to index.qmd.

Title it with your name and your CWL, like ## Ada Lovelace (adalove). We use this for your individual marks, so get the CWL right.
Put your merge conflict screenshot on it. Keep the images in one folder and name yours with your CWL, so four people adding screenshots do not overwrite each other.
Add anything else you like. The screenshot is the graded part.

What the screenshot has to show

The conflict inside the .qmd file, in your editor, with the <<<<<<<, =======, and >>>>>>> markers visible and readable.

These do not count:

git status saying you have a conflict
the output of git pull origin main
an editor’s “resolve conflict” button panel on its own

You are proving that you triggered a merge conflict and looked at it. The markers in the file are the proof.

Crop it if you like, keep the file name visible if you can, and make the text large enough to read.

If you are not with your group when you do this

You can create a real conflict with yourself, the same way we did it in class:

Edit index.qmd on GitHub in your browser and commit the change there.
On your laptop, without pulling first, change the same line to something different and commit.
Pull.

Git now has two versions of that line and hands you the conflict. Screenshot it, then resolve it as in Step 4.

Check that what you leave on GitHub is what you meant to keep. This is the fallback, not the plan.

Step 6: Publish and export

Pick one person to render

Rendering overwrites index.html and whatever else your setup generates. If four people render and push that, you get conflicts in generated files. Those teach you nothing.

Pick one person for the final render and push. Everyone else stops editing index.qmd and pushes their last change first.

Three things have to be true when you finish:

The slides are live at their GitHub Pages URL. How you get them there is up to you.

Read git status before you push. Generated clutter such as .quarto, _site, and .DS_Store does not belong in the repository. Ignore files are covered in this week’s lecture and are a good way to handle it. We grade what ended up committed, not how you kept it out.
That URL is in the repository’s About section. That is the panel on the right of the repository’s main page on github.ubc.ca, edited with the gear icon. Put the slides URL in the Website field and add a one-line description.
A PDF export of the deck is committed to the repository. The PDF should be in the repository alongside the slides, not only on your laptop. We open it from there.

Reveal.js slides are printed from the browser rather than rendered to PDF, which is not obvious the first time. Quarto: Presenting Slides has the route, including the ?print-pdf view and the print settings that make it look right.

Check the live GitHub Pages site, not just your own machine

We grade your submission based on what we see online: in your repository and on your repository’s GitHub Pages. You need to make sure that everything works there, not only on your laptops.

For example, images are the typical problem: a path that works locally can break once the site is served.

Click through every slide on the live site.
Have someone outside your group open the URL too. That tests your visibility setting at the same time.
Do not test in a private or incognito window. github.ubc.ca is behind your CWL login, so a logged-out browser shows a login page rather than your slides. That does not mean your site is broken.

Step 7: Submit

Follow instructions for submisson on Gradescope. We will only need you to submit URLs. Everything else is graded from the repository itself: the slides through the link in its About section, and the PDF from the files.

One submission per group (not one per person!)

Your group makes one (1) submission, and the person who makes it adds the other members to it in Gradescope.

You can add group members after the person does the first submission.

Do not submit your own copy.
An individually submitted assignment does not count as submitted.
It is everyone’s responsibility to check that their own name is on the single group submission. Open it in Gradescope and look.

If your name is not on it, you have not submitted, whatever your group tells you.

The repository is graded at the last commit timestamped before the deadline. Submitting on Gradescope does not extend that, and neither does a push that lands a minute late.

Grading

We are not marking the content of your presentation, just the execution of steps.

Item	Marks
Deck renders as reveal.js from `index.qmd` and is live on GitHub Pages	2
Slides URL is set in the repository’s About section	1
Four question slides, with every member’s answer on the same slide as everyone else’s	5
One personal slide per member, titled with their name and CWL	3
Each member’s screenshot shows real conflict markers inside a `.qmd` file	5
Every member has commits in the history under their own account	2
PDF export committed to the repository	1
One group submission on Gradescope, with the repository URL and every member added	1
Total	20

Every mark is a group mark. The whole group gets the same score, including the screenshot and commit rows. If a member does not do their part, the group loses those marks.

Files that do not belong in the repository cost marks. We are not grading whether you have an ignore file, only what you committed.

You do not have to prove a conflict in the commit history. The screenshot is the evidence we want.

If your group is short-handed

The deadline does not move. If someone is unwell, away, or unreachable:

Tell your instructor by Thursday, as in the note at the top.
Submit what you have, with slides for the members who took part.
Say so in the Gradescope submission.

A group of three does everything with three answers per question slide instead of four.

If you get stuck

Textbook: Asking Effective Questions

Ask in the 521_platforms-dsci Slack channel or come to office hours. Post the command you ran and the error message you got, not just “it did not work”.

If you have made a mess of the repository, say so early. Every conflict in this lab is recoverable, and untangling one with the isntructor’s or TA’s help in the lab is faster and teaches you more than deleting the repository and starting over.