In this hands-on workshop we will be covering version control systems (a.k.a. source control): what they are, why every coder needs them, and how to use the popular source control tool git for solo and collaborative coding.

The repository is available here: https://github.com/brown-ccv/how-to-pr

<aside> ⚡ To take part, you’ll need a github.com account – go to github.com/join and sign up now

</aside>

Different snapshots of code are easy to merge with git

<aside> 🔥 A distributed version control system (VCS) records computer files – their histories and variants – and helps with merging different variants.

</aside>

Git makes snapshots of a set of files, each time they are “committed” (or ”checked-in”)

Diagram of 5 versions of three different files. From https://git-scm.com/book/en/v2/Getting-Started-What-is-Git%3F

Git makes branching and merging easy – vital when you’re sharing the coding effort with others

A series of commits on two branches. Adapted from https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging

Read more

Every coder needs a version control system, and it might be git

Practical exercise: first “branch”, then make changes, then merge

<aside> 🎯 Aim for the Workshop

Collectively format a copy of the Wikipedia page about Git using “Markdown,” one of the text formats which GitHub uses for README files, comments on code, etc.

</aside>

Get Started with GitHub and VSCode

• Branch

  • Choose an issue.

    Issue

  • Clone the repository.

    Clone

  • Make a “branch” which can be shared, where you can make changes.

    Branch

  • Make a series of “commits” where you actually fix the issue, bit-by-bit.

    Commit

  • “Push” your branch to GitHub.

    Push

  • Make a “pull request” (PR) which requests to incorporate (”pull”) the changes in your branch into the main branch.

    Create Pull Request

• Merge

  • Reviewers will have the chance to look at the PR and (usually) suggest changes and improvements, or to say “this is great, let’s merge it!”

    Review Pull Request

  • Someone will merge the approved PR (or close it otherwise).

    Merge Pull Request

  • After merging, the now-defunct branch can be deleted.

    Clean Up

  • Everyone will update their now-outdated-PRs to incorporate the new merged changes, before they too are merged.

    Update

  • If people work on the same part of the document, then the authors will resolve the conflicting changes.

    Merge Conflict

Related Topics

• Set up checks to ensure that only approved and working PRs can be merged into main.

  Branch Protection Rules

• The CCV uses conventional names for issues, pull requests, branches and commits.

  Conventional Names

• Setting up your GitHub organization for collaboration using more advanced tools.

  Set up your Organization to use Academic Privileges