Update Git Usage Page

.github/workflows/sphinx-compile-test.yml

@@ -18,9 +18,10 @@ jobs:
         uses: actions/checkout@v4
         with:
           submodules: 'true'
-      - name: Install Sphinx
+      - name: Install Sphinx and Graphviz
         run: |
-          sudo apt install python3-sphinx-rtd-theme
+          sudo apt-get update
+          sudo apt install -y python3-sphinx-rtd-theme graphviz
       - name: Setup Pages
         id: pages
         uses: actions/configure-pages@v5

.github/workflows/sphinx-github-pages-deploy.yml

@@ -31,9 +31,10 @@ jobs:
         uses: actions/checkout@v4
         with:
           submodules: 'true'
-      - name: Install Sphinx
+      - name: Install Sphinx and Graphviz
         run: |
-          sudo apt install python3-sphinx-rtd-theme
+          sudo apt-get update
+          sudo apt install -y python3-sphinx-rtd-theme graphviz
       - name: Setup Pages
         id: pages
         uses: actions/configure-pages@v5

conf.py

@@ -49,3 +49,8 @@
 latex_elements = {
   'extraclassoptions': 'openany,oneside'
 }
+
+extensions = [
+    'sphinx.ext.graphviz',
+    # other extensions
+]

general/best-practices/git-best-practices.rst

@@ -0,0 +1,26 @@
+Git Best Practices
+==================
+
+**For developing features**
+
+1. Prirotize using rebasing over merging. This will help keep the commit history clean and linear.
+2. Only the PR owner should merge the PR. (Unless the PR owner is unavailable, then the PR owner should assign another team member to merge the PR.)
+3. Feature Branch name rule should be descriptive and follow the structure: `<watid>/<feature-name>`. For example, `j7zang/pic18f26k83-i2c-master-driver`.
+4. Open a draft PR as soon as new feature branch is created, and set it as a draft PR, and only remove draft status of the PR when the PR is ready for review.
+
+**For reviewing PR**
+
+1. If you have any concerns or questions about the PR, please discuss them with the PR owner before approving the PR.
+2. Make sure you are following the project's revelant standards and guidelines(electrical standard/firmware standard) when reviewing the PR.
+3. Provide constructive feedback and suggestions for improvement in the PR comments.
+4. Every PR should be reviewed within 3 days of being opened. If you are unable to review the PR within this time frame, please let the PR owner know.
+
+**Specific to software**
+
+1. For every commit message, you should follow the `Conventional Commits <https://www.conventionalcommits.org/en/v1.0.0/>`_ specification. This will help us generate changelogs and version releases automatically.
+2. Please configure the develop environment to run the code and test the changes before approving the PR.   
+
+**Contents of a Git repository**
+
+1. `.gitignore` files should be used to exclude files and directories that should not be tracked by Git.
+2. `.github/CODEOWENERS` files should be used to specify who is responsible for reviewing and approving changes to specific parts of the codebase. This will help ensure that changes are reviewed by the appropriate team members.

general/best-practices/index.rst

@@ -0,0 +1,8 @@
+Best Practices
+==============
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Best Practices
+
+   git-best-practices.rst

index.rst

@@ -7,13 +7,14 @@ Waterloo Rocketry Documentation Site
    :maxdepth: 2
    :caption: General
 
-   general/index.rst
    general/standards/index.rst
+   general/best-practices/index.rst
 
 .. toctree::
    :maxdepth: 2
    :caption: Onboarding & Tutorials
 
+   onboarding-tutorials/git-usage/index.rst
    onboarding-tutorials/electrical-onboarding/index.rst
    onboarding-tutorials/software-onboarding/index.rst
    onboarding-tutorials/firmware-how-to/index.rst

onboarding-tutorials/git-usage/git-basics.rst

@@ -0,0 +1,168 @@
+Git Basics
+==========
+
+**Note: Git is not Github, they are two different things.**
+
+Git is a distributed version control system, but Github is a web-based platform
+based on Git to host our codebase. 
+
+Introduction to Git
+-------------------
+
+Git is a distributed version control system that allows you to track changes in
+our codebase. It is a powerful tool that can people to work together on the same
+codebase without stepping on each other's toes.
+
+There are three main areas where you will interact with Git:
+
+1. **Your local repository** - This is where you will make changes to the codebase.
+
+3. **The staging area** - This is where you will prepare your changes to be committed.
+
+2. **The remote repository** - This is where the codebase is stored and where you will push your changes.
+
+.. graphviz::
+
+    digraph git_flow {
+         rankdir=LR;
+         node [shape=rectangle];
+         Local_Repository -> Staging_Area -> Remote_Repository;
+    }
+
+
+Sometimes you need to collaborate with others on the same codebase. In this case,
+we will introduce the concept of branches. A branch is a separate line of development
+that allows you to work on a feature without affecting the main codebase. Once you
+are done with your feature and reviewed by peer developers, you can merge your branch
+back into the main codebase. This is called a **pull request (PR)**.
+
+.. graphviz::
+
+    digraph git_flow {
+        rankdir=LR;
+        node [shape=circle, style=filled, fontcolor=white, width=0.5, fixedsize=true];
+
+        // Define nodes for the develop branch (yellow)
+        Develop1 [label="", color="#FFD700"];
+        Develop2 [label="", color="#FFD700"];
+        Develop3 [label="", color="#FFD700"];
+
+        // Define nodes for the feature branch (pink)
+        Feature1 [label="", color="#FF69B4"];
+        Feature2 [label="", color="#FF69B4"];
+        Feature3 [label="", color="#FF69B4"];
+
+        // Labels for branches without background
+        FeatureLabel [shape=plaintext, label="Feature", fontcolor="#FF69B4"];
+        DevelopLabel [shape=plaintext, label="Develop", fontcolor="#FFD700"];
+
+        // Arrange labels at the top and align nodes in the same rank
+        {rank=same; FeatureLabel -> Feature1 [style=invis]}
+        {rank=same; DevelopLabel -> Develop1 [style=invis]}
+        {rank=same; Feature1 -> Feature2 -> Feature3}
+        {rank=same; Develop1 -> Develop2 -> Develop3}
+
+        // Connect nodes to show the commit flow
+        edge [style=solid, color=black];
+        Develop1 -> Feature1 [arrowhead=normal];
+        Feature3 -> Develop2 [arrowhead=normal];
+    }
+
+That's it! You now have a basic understanding of Git and how to use it to work
+on a codebase.
+
+Installing Git
+--------------
+
+To get started with Git, you will need to install Git on your machine. 
+
+* Windows users
+    1. You can download Git from the `official Git website <https://git-scm.com/downloads/win>`_.
+    2. Run the installer and follow the instructions.
+    3. Once installed, you can open Git Bash to start using Git.
+    4. You can verify that Git is installed by running:
+         ``git --version``
+
+* Mac users
+    1. Run the following command in your terminal:
+       ``xcode-select --install``
+    2. xcode-select will prompt you to install the command line developer tools. Click "Install".
+    3. Command line developer tools include Git. You can verify this by running:
+         ``git --version``
+
+* Linux users
+    1. Run the following command in your terminal:
+       ``sudo apt-get install git``
+    2. You can verify that Git is installed by running:
+         ``git --version``
+
+Once you have Git installed, you need to configure your Git username and email.
+This is important because every Git commit will use this information to identify
+you as the author of the commit.
+
+To configure your Git username and email, run the following commands:
+
+.. code-block:: bash
+
+    git config --global user.name "Your Name"
+    git config --global user.email "
+
+Now you are ready to start using Git!
+
+Github Repository
+-----------------
+
+We use Github to host our codebase. Github is a web-based platform that allows
+you to store and manage your codebase. It also provides tools for collaboration
+such as pull requests, issues, and project boards.
+
+To connect your local repository to the remote repository on Github, you will
+need to create a Github account and get upload your public SSH key to Github.
+
+To create a Github account, go to the `Github website <https://github.com>`_ and
+follow the instructions to create an account.
+
+SSH Key is a secure way to connect to Github without having to enter your
+username and password every time. To generate an SSH key, run the following
+command in your terminal:
+
+.. code-block:: bash
+
+    ssh-keygen -t rsa -b 4096 -C "github-verify-ssh"
+
+This command will generate an SSH key pair. You will be prompted to enter a
+passphrase. You can leave it blank if you don't want to enter a passphrase.
+
+Once the SSH key is generated, you can add it to your SSH agent by running:
+
+.. code-block:: bash
+
+    eval "$(ssh-agent -s)"
+    ssh-add ~/.ssh/id_rsa
+
+Now you can copy the public SSH key to your clipboard by running:
+
+.. code-block:: bash
+
+    cat ~/.ssh/id_rsa.pub | pbcopy
+
+Now you can add the SSH key to your Github account. Go to your Github account
+settings, click on "SSH and GPG keys", and click on "New SSH key". Paste the
+public SSH key into the text box and click "Add SSH key".
+
+Now you are ready to connect your local repository to the remote repository on
+Github.
+
+Clone Onboarding Repository
+---------------------------
+
+Run the following command to clone the onboarding repository:
+
+.. code-block:: bash
+
+    git clone https://github.com/waterloo-rocketry/software-onboarding.git
+
+Read the README.md file in the repository to get started with the onboarding process.
+
+Congratulations! You have enough knowledge to get started with Git and Github. To check 
+out Git Commands, go to the next page.

onboarding-tutorials/git-usage/git-command.rst

@@ -0,0 +1,42 @@
+Git Common Commands
+-------------------
+
+This section will cover common `git` commands that you will use frequently.
+
+* ``git init``: Initializes a new Git repository. You should run this command in the root directory of your project.
+* ``git clone <repository-url>``: Clones a remote repository to your local machine. You should run this command in the directory where you want to store the repository.
+* ``git status``: Shows the status of your working directory and staging area.
+* ``git add <file>``: Adds a file to the staging area.
+* ``git commit -m "<message>"``: Commits the changes in the staging area to the repository.
+* ``git push``: Pushes your changes to the remote repository.
+* ``git pull``: Pulls changes from the remote repository to your local repository.
+* ``git log``: Shows the commit history of the repository.
+* ``git branch``: Shows the branches in the repository.
+* ``git checkout <branch-name>``: Switches to the specified branch.
+* ``git checkout -b <branch-name>``: Creates a new branch and switches to it.
+* ``git merge <branch-name>``: Merges the specified branch into the current branch.
+* ``git remote -v``: Shows the remote repositories associated with your local repository.
+* ``git remote add <name> <url>``: Adds a new remote repository to your local repository.
+* ``git remote remove <name>``: Removes a remote repository from your local repository.
+* ``git fetch``: Fetches changes from the remote repository.
+* ``git reset --hard HEAD~1``: Resets the working directory and staging area to the commit before the last commit.
+* ``git reset --soft HEAD~1``: Resets the staging area to the commit before the last commit.
+* ``git reset --hard <commit-hash>``: Resets the working directory and staging area to the specified commit.
+* ``git blame <file>``: Shows the commit history of a file, including who made each change.
+* ``git diff``: Shows the differences between the working directory and the staging area.
+* ``git diff --staged``: Shows the differences between the staging area and the repository.
+* ``git stash``: Stashes changes in the working directory and staging area.
+* ``git stash pop``: Applies the most recent stash to the working directory and staging area.
+* ``git stash list``: Shows a list of stashes.
+* ``git tag <tag-name>``: Creates a tag for the current commit.
+* ``git tag -a <tag-name> -m "<message>"``: Creates an annotated tag for the current commit.
+* ``git tag``: Shows the tags in the repository.
+* ``git push --tags``: Pushes tags to the remote repository.
+* ``git push origin --delete <branch-name>``: Deletes a remote branch.
+* ``git branch -d <branch-name>``: Deletes a local branch.
+* ``git config --global user.name "Your Name"``: Configures your Git username.
+* ``git bisect``: Helps you find the commit that introduced a bug.
+
+These are just a few of the many `git` commands available. You can find more commands and options in the `git documentation <https://git-scm.com/doc>`_.
+
+What's Next? Now that you have learned the basics of `git`, you can move on to learn our team  :doc:`Git Best Practices </general/best-practices/git-best-practices>`.

onboarding-tutorials/git-usage/index.rst

@@ -0,0 +1,12 @@
+Git Tutorial
+============
+
+This guide is intended to help you get started with `git`, it covers the
+basics of using `git`. For team specific git guidelines refer to :doc:`Git Best Practices </general/best-practices/git-best-practices>`
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Tutorial
+
+   git-basics.rst
+   git-command.rst