GitHub Starter Guide

So, you made the (fortunate) decision to use GitHub for your CRP project team.

What is Git? What is GitHub?

Git is a distributed version control system that allows developers to track changes in their codebase, collaborate with others, and manage project history efficiently. It provides features like branching, merging, and reverting changes to ensure smooth development workflows.

GitHub is a web-based platform that hosts Git repositories, enabling developers to share their code, collaborate on projects, and contribute to open-source software. It offers additional features like issue tracking, pull requests, and project management tools to enhance team collaboration.

Why does The Data Mine recommend GitHub?

GitHub makes it easy to manage code for a project-based class like ours since it facilitates seamless collaboration and version control (if used properly). This ensures that all contributors can work on the project simultaneously without conflicts. Additionally, GitHub’s features like pull requests and issue tracking help maintain clear communication and organization, making it easier to integrate feedback from corporate partner mentors and manage project progress.

While it can take a little bit to get used to, it’s significantly better than file drops!

Useful Bash Commands

  • pwd - Print Working Directory (prints the path to your current directory/- folder)

  • mkdir - Make Directory (creates a folder)

  • ls - List Directory

  • cp - Copy file or directory

  • cat - Prints the whole file

  • cd - Change directory

  • mv - Move file or directory

  • rm - Deletes a file

How should we structure our GitHub repository?

Let’s try to bake a cake! It’s important to define the input and output to the system, allowing us to break down the larger problem into smaller tasks students can latch onto.

Flowchart of cake baking process, with defined inputs and outputs
Figure 1. Software Architecture Diagram for Baking a Cake

  • conductor.py

  • testing.ipynb

  • inductor.sh

  • SETUP

    • ingredients.py

    • __init__.py

  • UTENSILS

    • mixer.py

    • bowl.py

    • pan.py

    • __init__.py

  • APPLIANCES

    • fridge.py

    • oven.py

    • __init__.py

conductor.py (and testing.ipynb) are your primary playground. They import your other functions and handles the input and output between them.

inductor.sh summons the use of the seminar kernel when running conductor.py from the terminal

The rest of the files are python scripts that have functions. I recommend one function (and one student) per script.

Each __init__.py helps conductor.py know what custom functions live in each of your student’s scripts.

Useful Git Commands

  • git clone repository-name - clone repository

  • git add filename - add file to staging area (make it ready to be committed)

  • git rm filename - remove file from staging area

  • git commit -m "message/comment" - commit the changes to the local branch (ready to be pushed to the remote repo)

  • git push origin branchName - push it to the remote repo (MAKE SURE YOU CLARIFY ORIGIN AND BRANCH NAME)

  • git branch - Check what branch you are currently in

  • git branch branchName - Create a branch with that name

  • git checkout branchName - Change to that branch

  • git status - Check the status of the git repo

How do we use branches?

A branch should be created to work on a SINGULAR modification or new feature. This will limit the potential for merge conflicts and aid in student work ownership. Branches typically will be made off the main branch. When the student is ready to send in work they can push to the remote and close the branch after the merge is completed by the TA or mentor.

What is contained in a good commit message?

Commit messages should be short but adequately communicate the changes made with the code.

Example files

conductor.py

from SETUP import *
from UTENSILS import *
from APPLIANCES import *

Def main():
   # Do cool things!
   return None

if __name__ == '__main__':
    import cProfile
    main()

inductor.sh

module use /anvil/projects/tdm/opt/core

module load tdm

module load python/seminar

python3 conductor.py

__init__.py

# import a function from a file like "fridge.py" in the same directory
from .fridge import wetIngredients
from .oven import bakeTheCake