Skip to content

EX00 - Collaborating on Technical Documentation

Learning Objectives

Welcome to your first pair project! This exercise aims to build your skills in several key areas:

  • Starting Projects: Learn how to create a new project using today’s development tools and be empowered to start your own!
  • Using Technical Documentation: Get better at finding, reading, and using guides and manuals to achieve your goals on your own.
  • Writing Technical Documentation: Improve at writing clear instructions for others on how to do technical tasks.
  • Teamwork with Git: Develop your ability to work with others using git, focusing on how to manage changes and updates in your work effectively.

Workflow Expectations

We are prescribing, and grading on, some very specific workflow expectations in this exercise:

  • All merges in this exercise must produce merge commits, thus always use the --no-ff flag when merging in this exercise. The git merge --no-ff <source-branch> command is short for no fast-forward and produces a merge commit where fast-forwarding was otherwise possible. This is how we will see your history of branch use.
  • Before merging locally, be sure you have pushed your branch to your repository.
  • Only you are permitted to merge into main on your own repository. You can push branches to your partner's repository.
  • We will NOT use Pull Requests yet in order to apply our understanding of git's fundamental collaboration commands (fetch, branch, switch, merge, pull, and push)

Deliverable Overview

You and your partner will work together to produce:

  1. Tutorial Guides (50 points): Each of you will write a tutorial for setting up a basic project from scratch, one of you for the Go programming language and the other for the Rust programming language. You’ll publish your guide on your personal MkDocs site. Your partner will help by reviewing and suggesting improvements to your guide.
    • 20 points - Well fomatted markdown and use of appropriate MkDocs for Material features (e.g. text formatting, bullets/enumerations where meaningful, subheadings, code blocks, and admonitions). Hint: Markdown reference.
    • 30 points - Tutorial includes required components (brief intro, git repo setup, dev container setup, initialize a project, add a hello world example, compile and run)
  2. Project Repositories (20 points): Host the starter projects resulting from your tutorials on GitHub and make them public. Project repositories will need a README.md in the root directory that link out to your tutorial on your course notes site.
  3. EX00 Git Workflow Adherence (30 points): You will be asked to show how you followed the specific git workflow expectations we have in this exercise. This will be preserved in your git repository's history (e.g. via log) and we will show you how to share it via your GitHub repository. Read Workflow Expectations Above BEFORE Beginning!

Tutorial Anti-patterns

  • Besides VSCode, Docker, and git, users should not install any software directly to their host machine. That is the role of the dev container! (Instructions which install Go or Rust to the host machine will be a -25pt penalty.)
  • When compiling Go or Rust in the Dev Container, since it is running Linux, you do not expect to see .exe file extensions anywhere in this project. That is a sign you are running something on the host machine.

Initial Setup: Partner Repository Access and main Ruleset

You need to give your partner access to your repository and get access to theirs.

Setting Up Repository Access

Navigate to your comp423-course-notes repository on GitHub (the one you created in the previous tutorial) and follow these steps:

  1. Go to Settings > Collaborators
  2. Click "Add people"
  3. Enter your partner's GitHub username
  4. Select their account and send the invitation

Your partner will need to accept the invitation via email or through GitHub's interface before they can contribute to your repository. Make sure you both complete this step before proceeding.

Protecting Your Repository with Rulesets

Even though you've added your partner as a collaborator, you'll want to protect your main branch through a ruleset. Rulesets are GitHub's approach to repository security, allowing you to define who can make what kinds of changes to your codebase. Let's set up a simple one and understand what each setting does.

Navigate to your repository's Settings page on GitHub and follow these steps:

  1. Click on "Rules" > "Rulesets" in the left sidebar under "Code and automation"
  2. Click "New ruleset" > "New branch ruleset" to create a ruleset
  3. Configure your ruleset with these settings:

Basic Settings:

  • Name your ruleset main
  • For "Enforcement status," select "Active"
  • Bypass list: Add "Repository admin" (this is you, the repository owner)
  • Under "Target branches" choose "Add target" and select "Include default branch" (this is main)

Rules:

  • Enable "Restrict creations"
  • Enable "Restrict updates"
  • Leave everything else as is. The following two settings should be checked by default:
    • Enable "Restrict deletions"
    • Block force pushes

Let's understand what each of these settings means and why they're important:

Targeting the Default Branch: Your default branch (in your project, this is main) is the primary branch of your repository.

Restrict Creations, Updates, and Deletions: These three settings work together to control who can make changes to your default branch. When enabled, only people in the bypass list (in this case, just you) can create new commits on the primary branch, update existing commits, overwrite the branch (force push) or delete the branch entirely.

These rules reflect a simplified real-world setup. Your partner can create branches, make changes, and push their branches to share with you - they just can't modify the protected main branch directly. That's your job!

Cloning Your Partner's Repository

Since you already have your own repository set up locally from the previous tutorial, you just need to clone your partner's repository. Because both repositories have the same name, you'll want to specify a different directory name when cloning to avoid conflicts. The target directory name is added as an extra command-line argument following the repository URL:

# Clone your partner's repository with a descriptive directory name
git clone https://github.com/<partner>/comp423-course-notes.git partner-notes

After cloning, open your partner's notes site in the new directory in VS Code and then reopen the workspace in a dev container, just as you did with your own repository in the previous tutorial.

Pay Attention To Which Project You Are Working On

When working on this exercise, be sure you know whose project repository you are working in! In this exercise each of you owns your own repository and will be practicing contributing to your partner's repository.

As a rule of thumb, when returning to work in VS Code, go to your "File" menu, "Open Recent", and select the directory with "[Dev Container]" that you intend to work on. If you're already in it, nothing happens. If you're switching between projects, your the new dev container will open.

Finally, it is possible to have both dev containers running simultaneously. However, you cannot have both MkDocs dev servers available simultaneously on the same port. The most straightforward way around this is to start mkdocs serve with the -a (address) flag and provide an alternate port (e.g. mkdocs serve -a localhost:4230). In the event you forget to to do this, Docker will try to avoid the conflict by forwarding a different port on your host machine to your container port. To see these mappings in VS Code, go to the Ports tab (typically next to Terminal) or open up the Command Palatte and search for Focus on Ports View. Look for the forwarded address.

Direct Git Collaboration Workflow

In this exercise, you will rely on Git's fundamental commands to share and integrate changes. This approach helps you practice your understanding of Git's branching model. Here's the basic flow:

  1. You work on changes in your own repository
  2. Your partner clones your repository, makes suggestions in a branch, and they push their branch to your repo
  3. You fetch their suggestions locally and switch to their branch to consider the work
  4. After reviewing and testing, you merge changes into your main branch (with --no-ff to preserve the history!)
  5. You push the updated main branch back to GitHub to deploy your site

This workflow requires careful coordination and communication between team members and a solid understanding of Git's core commands. Let's explore how to use these commands effectively.

Do All of Your Work in Branches!

Always create a new branch for work you're about to embark upon:

# Do you have any uncommitted work?
#     Yes? Decide what to do with it!
#     No? Great!
# Are you on the right starting branch for new work?
#     No? switch to where you want to branch from (usually main)
#     Yes? Great!
git status

# Create and switch to a new branch with a meaningful name
# Of course, substitute <meaningful-name> with something... meaningful
git switch -c <meaningful-name>

# As you work, commit regularly with meaningful messages
git add <directory or file(s)>
git commit -m "<message>"

Share Your Work

When ready to share your changes for your partner to check out:

# Push your meaningfully named branch to GitHub
# Note: Use the same branch name locally as remotely!
git push -u origin <meaningful-name>

Go convince yourself the branch push worked by opening GitHub, clicking the Branch Dropdown (it should show main) and selecting your branch. Let your partner know the branch you shared by its name and/or by sharing a link directly to the branch on Github.

Reviewing Partner's Work

When your partner has pushed changes for review, open your copy of your partner's dev container project and then:

  1. Fetch the latest changes from the project's repository: 

    git fetch origin

  2. Switch to the branch they just pushed 

    git switch <branch-name-partner-pushed>

  3. Review their changes locally, running their tutorial to verify it works. If you'd like to see the specific changes made relative to your main branch, or any other branch, you can use the diff subcommand of git:

  4. In the terminal: git diff main - press Space to move forward page-by-page and q to exit. The diff shows additions (in green) and removals (in red).

  5. On GitHub: View the branch, look for the Contribute button drop down, click it and select Compare (not Pull Request). You will see a diff of the changes.

  6. To make your own suggested edits to their work, go ahead and start a branch: 

    git switch -c edits/<branch-name-partner-pushed>

  7. Make your changes, add commit(s) with meaningful commit messages, then push your edits: 

    git push -u origin edits/<branch-name-partner-pushed>

Let your partner know the name of the branch you pushed edits to their work on.

Merging a Partner's Changes

Ready to review the edits your partner pushed to your repo? Be sure you have your dev container open, then follow the same steps as reviewing partner work above, but use the branch name they pushed.

Once you're ready to merge their work into your branch, or main, or your own work into main, the steps are as you already know with one minor twist: for this exercise, always use the --no-ff flag to preserve the merge history:

# First, switch to the target branch you're merging into
git switch <target branch>

# Best practice: be sure your branch is up-to-date
git pull origin <target branch>

# Merge your source branch and force a merge commit 
git merge --no-ff <source branch being merged in>

# Push the merged changes to GitHub
git push origin <target branch>

Class Meeting 04 - Practice Exchange

Decide which of you will do a tutorial on Go and the other on Rust. If your partner is not in class, you get first dibs on either!

  1. Create and switch to a branch in your project named mt04-setup
  2. Create a directory named docs/tutorials
  3. Add a file named docs/tutorials/rust-setup.md or docs/tutorials/go-setup.md, whichever you are going to be working on, with the following contents: 
    # Setting up a dev container for <Insert: Go or Rust depending on which you are doing>

* Primary author: [<Your Name>](https://YourGitHubProfileLink)
  4. Verify your work in your local development server (mkdocs serve)
  5. Push the branch to your repo (see Share Your Work above)
  6. Let your partner know and they should follow the steps of Reviewing Partner's Work (above)
  7. Your partner should create a new branch named edits/mt04-setup and add the following changes to your setup markdown file below the primary author line: 
    * Reviewer: [<Partner name>](https://PartnerGithubProfileLink)
  8. Your partner should commit and push their branch to your repo
  9. You should fetch changes, then switch to their branch and see their contribution
  10. You should switch back to your work branch (mt04-setup) and merge their work in with --no-ff. Then push to your mt04-branch.
  11. You should switch back to your main branch and merge your work in mt04-setup with --no-ff. Then push your main branch. Your site should publish successfully with these changes!

Review the commit graph history:

  1. In your dev container terminal git log --graph --oneline and notice the merge commits and where branches are.
  2. In your GitHub repository, go to the Insights tab, select Network. You should see your commit graph with tags here.

Ultimately, when proving that you are following the workflow expectations with your partner for this assignment, you will submit a screenshot of these graphs as a record of the branches and merges made.

Assignment Structure

You and your partner will each create a tutorial about setting up a new DevContainer project. One of you will focus on Go, while the other will work on Rust. Here's how to organize the work:

  1. Update your mkdocs.yml to include the required markdown features. You can enable whatever other features you would like, too!
  2. Write your tutorial in either docs/tutorials/go-setup.md or docs/tutorials/rust-setup.md (one per team mate course notes site)
  3. Share your tutorial branch with your team mate, they should follow along and add helpful additions, corrections, or suggestiosn along the way. They will push their brach back to your repo.
  4. You iterate off of their pushed branch and incorporate back into your work.
  5. You finalize your tutorial and merge into main
  6. You follow your tutorial from start to finish and publish the resulting repository in a public repo on your GitHub account. Its README.md should link back to your course notes site's tutorial.

Required Material for MkDocs Features to Enable

Before diving head first into your tutorial, there are a few helpful markdown features to enable in Material for MkDocs with your partner. Find how to enable these on the official website. Hint: try searching! Once you find reference for a particular feature, look at the sidebar for both configuration and usage examples.

Start a branch for mkdocs-extensions and enable the following features. After enabling each feature, try adding an example of how to use them in markdown to your tutorial draft.

Workflow Expectation: You setup code blocks in the branch. Your partner will check out your work and then incorporate admonitions in a branch off of your branch. You will then be responsible for merging all and pushing. If you've already individually enabled both features, let your partner find another feature to enable on your site (and do the same in exchange)!

  1. Code Blocks - for syntax highlighting of code
  2. Admonitions - for useful call-outs to draw attention to ideas or asides

Tutorial Content Requirements

Your tutorials should include:

  1. Prerequisites
  2. Step-by-step instructions for creating a new Dev Container project for your language
  3. Should start from a blank directory and include git initialization
  4. Dev Container configuration file explanations
  5. Steps to create a new project, write a basic "Hello COMP423" program, compile, and run
  6. The program's requirement is that it simply prints "Hello COMP423" out to standard output

Make use of Material for MkDocs features to enhance your documentation:

  • Code blocks with syntax highlighting for configuration files and commands
  • Admonitions for important notes and warnings

You can cite and reuse instructions from the 423 MkDocs tutorial if useful.

Need Help?

  • If you encounter Git issues, try running git status and git log to understand your current state
  • When in doubt, communicate with your partner about the current state of changes
  • For language-specific questions, consult the official language documentation and Google
  • Go documentation
  • Rust / Cargo documentation

Remember to commit early and often, and always use the --no-ff flag when merging to maintain a clear history of collaboration.

Go Tutorial Expectations

  • Dev container should use a base image from Microsoft (Hint: refer back to the MkDocs tutorial)
  • Be sure the Dev Container Installs the official Go VSCode Plugin (Made by the Go Team at Google)
  • Show the go version subcommand to prove a recent version of Go
  • Use the mod subcommand
  • Use the run subcommand
  • Use the build subcommand (discuss this in the context of COMP211's gcc command), run the built binary directly, and discuss the difference from run

Rust Tutorial Expectations

  • Dev container should use a base image from Microsoft (Hint: refer back to the MkDocs tutorial)
  • Be sure the Dev Container Installs the official rust-analyzer VSCode plugin by the Rust Programming Language Group
  • Show the rustc --version to prove a recent version of rust
  • Use the cargo new command to create a binary project (use the flag that does not create a new git repository automatically on your behalf: --vcs none (Version Control System))
  • Use the cargo build command and show how to run the built file (discuss in terms of COMP211's gcc command)
  • Use the cargo run subcommand and discuss difference with build