GitHub Rules and Expectations

It is important to have documentation for people to reference as they learn how to work in a team. One document I use when I'm onboarding a student onto one of my codebases is my GitHub Rules and Expectations. The basic idea is to give them a clear idea of how to interact with everyone when it comes to the codebase and step-by-step instructions on what to do in certain situations. Below is the current version of my document. And yes, the "Rationale for Rules" is a section under the rules, so the students understand why I'm asking them to follow the rules.


[Also posted on medium.]

Rules

  1. The main branch is only for final work and has a clean commit history

  2. Do not directly commit to the main branch

  3. Work In Progress (WIP) branches

    1. Use these for all initial work

    2. Tiny commits on these branches are perfectly acceptable

    3. It is fine to use a WIP for a pull request (PR) if its commit history is clean.

    4. These can and should be pushed to the repo to have backups of work.

  4. Clear commits that make the commit history clean have:

    1. A short description as its first line

    2. A clear description of what the commit contains

    3. (optional) Separate lists of the files this commit adds, deletes, and changes and notes on what was done if needed

  5. When renaming or moving files, use git mv, so Git is aware of what is going on

  6. Do not blindly use git add -a . Instead, carefully choose what files should be added and use a .gitignore file. Do commit the .gitignore file.

Rationale for Rules

Rules 1, 4, and 5 focus on making the main branch as readable as possible for current you, future you (the you that will forget all the nuances of your repo in a week or more), and anyone else that will interact with the repo.


Rule 2 is partially about readability and partially to help with the interaction between team members. Moreover, it encourages using pull requests and code reviews properly within the team because they are best practices when a team is sharing a repo.


Rule 3 is to lower the barrier of committing and putting things into the remote repo. In a WIP, nothing is too small to commit. Losing work is worse than tiny, nonsensical commits. No one will look at your WIP branch except you, unless you invite them.


Rule 6 is to prevent random additions of system-specific files or things that do not belong in the repo because of their size, they constantly change (like log files), etc.

Branches

Branch names should have the following structure to make it easy for others to find branches: 

USERNAME/[WIP/]PURPOSE

USERNAME - your username
WIP - include if this branch is a Work In Progress branch
PURPOSE - short name of what the branch is for

Pre-Code Review Checklist

  1. When running all tests (python3 -m unittest discover), do all tests pass?

  2. Reasonable whitespace?

  3. Any repetitive code or long functions that could be refactored?

Squashing a Branch and Pull Requests

When you are ready for your code to go into the main branch.


  1. git checkout -b BRANCH_NAME - Branch off the current working branch (this is usually off of a WIP branch, so use the same name but without WIP in the name)

  2. git rebase -i HEAD~NUM_OF_COMMITS - Use interactive rebase to squash the commits in this branch into as few commits as appropriate (the fewer, the better)

  3. git push - Push the new branch to the remote repo

  4. Create a pull request with the new branch - Use the GitHub interface to create the pull request (PR) from the branch and assign it to the appropriate person

  5. Once the code review is approved and you are ready to merge into the main branch, choose one of the following

    1. If the branch has no conflicts with the main/base branch and therefore can be done automatically

      1. If PR involves only one commit - Use the pull request interface to "Rebase and merge"

      2. If PR has multiple commits that just need to be squashed - Use the pull request interface to "Squash and merge"

    2. If PR has multiple commits that need to be reorganized or rebase/merge cannot be done automatically - Ask Prof. Stephens-Martinez for help. She will walk you through it or direct you to resources that will help.

  6. Delete all branches associated with these changes in local and remote repos unless you have a strong reason to keep them. Git will warn you for some of these branches that the commits aren't in main (squashing and rebasing look like new commits to git). So double check the correct branch is being deleted and delete anyway.

Git Mental Model that May Help

The entire commit history is a large graph.

  • A commit is a diff of changes to apply to the repo

  • Nodes are commits

  • Edges only exist within the context of a branch

  • The only branches existing in the graph at a given time are the ones that are interacting

  • Git makes copies of commits as it needs to keep the graph a directed acyclic graph


For more on this topic, here is a video lecture of me going more in-depth on the git mental model. The video is from my Fall 2022 post-CS2 data science class (CS216). The audio is scratchy, and that particulate lecture hall has mics to pick up audience questions. So it also picks up a bunch of crowd sounds.

Comments

Post a Comment

Popular posts from this blog

How I track my to-do list

This is also on medium . I use Trello  to track all the things I need to do. Trello, at its core, is just a to-do list management tool. It is versatile to many organization strategies and is great for a single person or a team to organize the tasks that need doing. However, this versatility can be very daunting as a novice because you are just starting to figure out a system to keep track of what you need to do. And a novice rarely does well in an environment where there are many ways to do the same thing, a.k.a. a versatile system. A beginner does not have enough experience to determine what technique is better than another. Moreover, a novice finds it challenging to keep track of the many ways to do the same thing. So, if you are a novice, here are my suggestions for how to use Trello to track your personal to-do list (how I use it to organize my research team(s) and teaching team(s) I'll leave for a different blog post). First, I'll go over the fundamental way I use Tre
Read more

How I Track The To-do List For My 200+ Student Class

Image
This is also  posted on medium . This is post #4 of a 5 post series on how I organize the teaching staff for my 200+ student class. This post discusses how I track all the class’s tasks. I start with an overview of Trello , the tool I use to track tasks. Next is a discussion on my overall task management approach. I then move on to how I use Trello to structure the task lists, common and recurring tasks, and a task’s life cycle. Finally, I close with the advantages I see for having an externalized task list. The other posts in this series are as follows (I’ll update with links as I post): Overview Teaching staff roles How I communicate with my teaching staff How I track the to-do list (You are here) How I run the head staff meetings Terminology Rather than require you to read my teaching staff roles post , here is a quick refresher: Teaching Associate (TA+)  — A full-time department staff member (not a student) assigned to my class. She serves as my right-hand person with many and var
Read more

GPS Syndrome

A term I made up and have been using for a while is "GPS syndrome." And it turns out that enough people have picked up this term that I feel like I need to post an "official" definition. I most commonly use the metaphor when talking about and with teaching assistants (TAs) that overhelp students. So this blog post is mostly from a google doc I wrote for new TAs for one of their training sessions. Definition " Scaffolding refers to a variety of instructional techniques used to move students progressively toward stronger understanding and, ultimately, greater independence in the learning process. The term itself offers the relevant descriptive metaphor: teachers provide successive levels of temporary support that help students reach higher levels of comprehension and skill acquisition that they would not be able to achieve without assistance. Like physical scaffolding, the supportive strategies are incrementally removed when they are no longer needed, and the
Read more