Adog64/Website
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Created blogging setup and first git blog post

Browse Source
This commit is contained in:
Adog64
2025-08-30 21:38:00 -07:00
parent f139605d25
commit aecd46304a
4 changed files with 265 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

169
mdblog/github-workflow.html Normal file
View File

@@ -0,0 +1,169 @@
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
<head>
<meta charset="utf-8" />
<meta name="generator" content="pandoc" />
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
<meta name="author" content="Aidan Sharpe" />
<title>Using GitHub for Project Management</title>
<style>
code{white-space: pre-wrap;}
span.smallcaps{font-variant: small-caps;}
div.columns{display: flex; gap: min(4vw, 1.5em);}
div.column{flex: auto; overflow-x: auto;}
div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
/* The extra [class] is a hack that increases specificity enough to
override a similar rule in reveal.js */
ul.task-list[class]{list-style: none;}
ul.task-list li input[type="checkbox"] {
font-size: inherit;
width: 0.8em;
margin: 0 0.8em 0.2em -1.6em;
vertical-align: middle;
}
.display.math{display: block; text-align: center; margin: 0.5rem auto;}
</style>
<link rel="stylesheet" href="../sharpe6style.css" />
</head>
<body>
<header id="title-block-header">
<h1 class="title">Using GitHub for Project Management</h1>
<p class="author">Aidan Sharpe</p>
<p class="date">August 30th, 2025</p>
</header>
<h2 id="what-github-brings-to-the-table">What GitHub Brings to the
Table</h2>
<p>There are a lot of reasons to use GitHub as a tool for managing
projects. For the purposes of this post, the most important are:</p>
<ul>
<li>Managing and tracking complex edit history</li>
<li>Tracking progress towards goals and deadlines</li>
<li>Developing a set of tasks and assigning them to team members</li>
<li>Peer-reviewed changes</li>
</ul>
<p>It is important to note that, as with any new tool or software, there
will be a learning curve. GitHub is a powerful tool that will take some
time to get used to. YOU WILL MAKE MISTAKES! That is normal and
perfectly fine. And in many cases, since versioning is built-in, you can
usually undo your mistakes rather quickly.</p>
<p><img src="https://imgs.xkcd.com/comics/git.png" /></p>
<p>This overview contains my opinions and personal recommendations on
how to use Git. I will periodically reference the <a
href="https://git-scm.com/book/en/v2"><em>Pro Git</em> book</a>, written
by Scott Shacon and Ben Straub, which provides much more polished and
in-depth explanations of these complex topics. I highly recommend that
you supplement this reading with <em>Pro Git</em>.</p>
<h2 id="getting-started">Getting Started</h2>
<p>The first step to using GitHub is <a
href="https://github.com/signup">making an account</a> if you do not
already have one. Then, if you are setting this up as part of a team,
ask whoever is in charge of adding people to the GitHub organization. A
GitHub organization can do everything your user account can do, plus
some extra features that assist with team management.</p>
<h3 id="installing-some-tools">Installing Some Tools</h3>
<p>While everything can be done from the command line, and the <em>Pro
Git</em> book will provide most of its guidance using the command line,
there is no doubt that you will have an easier time using a graphical
application. I have found that GitHub Desktop is one of the best tools
for this, since it is cross-platform and completely free. Some people
prefer GitKraken, but I find that it tries too hard to push its paid
features, and distracts you from what is actually important. You can
find GitHub desktop downloads <a
href="https://desktop.github.com/download/">here</a> or, on Linux, you
can install from Flathub.</p>
<p>GitHub is a website built around Git, a powerful version control
tool. Therefore, you must also have Git installed. You can find
installation instructions for your operating system <a
href="https://git-scm.com/downloads">here</a>.</p>
<h2 id="basic-git-concepts">Basic Git Concepts</h2>
<p>With everything installed, we can start with some basic concepts.
Here we will discuss the major elements you will interact with while
using Git. Some you will already be familiar with just from using your
computer or other versioned tools, but some will be more foreign.</p>
<h3 id="the-repository">The Repository</h3>
<p>A Git repository, commonly called a repo, is the top-level folder
containing all other folders and files for your project. There is not
one single right way to use a repository, but we’ll get started with a
basic rule of thumb: one repository corresponds to one product. Here are
some examples of what might constitute a repository:</p>
<ul>
<li>A circuit board project containing all schematics, board layout
files, gerbers, SPICE simulations, and other exported files</li>
<li>A mechanical project containing a top-level assembly, all part
files, and a folder with mesh exports</li>
<li>A software project containing code, build files, and any files
required to build the project</li>
</ul>
<p>It might take some getting used to to figure out exactly when a new
repository is justified as opposed to just making a new folder inside an
existing repository. There are no strict rules, but you’ll figure out
what works best for you.</p>
<p>Regardless of where you decide to draw the lines, the purpose of the
repository is the same: to group files and sub-folders into a single
top-level folder, where all changes are tracked and versioned.</p>
<p>Git is a “distributed version control system”, which means that the
repository has a copy online (GitHub) and a copy on your computer. This
means that if something were to happen to your computer, you can restore
everything from the online copy, and if something were to happen to the
online copy, you could restore it from your computer. Therefore, Git is
very robust to data loss. Since you are working entirely off of files on
your computer, you don’t even need an internet connection to continue to
do work or for Git to track your changes. The only time you need
internet is when you want to get new commits from the online copy
(pulling changes) or when you want to copy your changes from your
computer to the online repo (pushing changes).</p>
<h3 id="commits">Commits</h3>
<p>A commit is a tracked set of changes. Think about it like a
checkpoint for your project, like how in Google docs, where you can see
previous versions go back to them, and see who made the changes. A
commit in Git is much more powerful, however. While in Google docs, the
“versions” are created automatically, in Git, you decide what
constitutes a version.</p>
<p>Each commit will contain something called a diff. The diff is the set
of additions, deletions, and modifications within a repository.
Essentially, it is the changes from one version to the next. These
changes can be as small as a single character in a single file, or as
big as the deletion of every file in the repository or adding hundreds
of new files. A good rule of thumb is to keep your commits complete, yet
self-contained. For example, if you are experimenting with a new fin
design on a rocket, rather than making a commit for each tiny change, a
complete commit would be the rocket after the new fin design is
finished. If you are doing multiple iterations of the design, each
iteration would be its own commit. Additionally, it probably doesn’t
make sense to have a new nose cone design <em>and</em> a new fin design
in the same commit, as you wouldn’t be able to undo one without undoing
both, hence the importance of keeping commits self-contained.</p>
<h3 id="branches">Branches</h3>
<p>Branches are one feature of Git that you probably would not be
familiar if you haven’t used a version control tool before. Most tools
that let you go back to previous versions in a linear manner. With Git,
changes can be made in parallel, and brought back together in the
future. To enable this, a tool called a branch is used. I highly
recommend reading <a
href="https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell">3.1
Git Branching - Branches in a Nutshell</a> to get a stronger
understanding of what branches are and how to use them.</p>
<p>A branch is simply a series of commits, but the important distinction
is that you can start a branch from any commit, and multiple branches
can start from the same commit. This enables parallel, non-destructive
editing. So if you make a mistake on a branch, it won’t affect the main
line of development.</p>
<p>Branches are typically broken up into two or three categories. First,
the main or master branch. This is the main line of development, where
the primary goal should be to have the latest working version of all
features. Work should never be done directly on the main branch, as
adding a bad commit could ruin other people’s work. This brings us to
development branches. Development branches are where most work should be
done, and they will be dedicated to a specific task. For example, you
may have a development branch for designing a schematic for an
individual circuit, or for adding a specific feature to a program.
Sometimes you may want to make a branch off of a development branch for
an experimental change. This would be called a topic branch. I find that
topic branches make things too complicated and hard to follow, so I tend
to avoid them where possible.</p>
<p><img src="https://git-scm.com/images/about/branches@2x.png" /></p>
<h2 id="workflows">Workflows</h2>
<p>Now that we understand some basic terms, lets look at how they fit
together.</p>
</body>
</html>

63
mdblog/github-workflow.md Normal file
View File

@@ -0,0 +1,63 @@
---
title: Using GitHub for Project Management
author: Aidan Sharpe
date: August 30th, 2025
css: ../sharpe6style.css
---
## What GitHub Brings to the Table
There are a lot of reasons to use GitHub as a tool for managing projects. For the purposes of this post, the most important are:
- Managing and tracking complex edit history
- Tracking progress towards goals and deadlines
- Developing a set of tasks and assigning them to team members
- Peer-reviewed changes
It is important to note that, as with any new tool or software, there will be a learning curve. GitHub is a powerful tool that will take some time to get used to. YOU WILL MAKE MISTAKES! That is normal and perfectly fine. And in many cases, since versioning is built-in, you can usually undo your mistakes rather quickly.
![](https://imgs.xkcd.com/comics/git.png)
This overview contains my opinions and personal recommendations on how to use Git. I will periodically reference the [*Pro Git* book](https://git-scm.com/book/en/v2), written by Scott Shacon and Ben Straub, which provides much more polished and in-depth explanations of these complex topics. I highly recommend that you supplement this reading with *Pro Git*.
## Getting Started
The first step to using GitHub is [making an account](https://github.com/signup) if you do not already have one. Then, if you are setting this up as part of a team, ask whoever is in charge of adding people to the GitHub organization. A GitHub organization can do everything your user account can do, plus some extra features that assist with team management.
### Installing Some Tools
While everything can be done from the command line, and the *Pro Git* book will provide most of its guidance using the command line, there is no doubt that you will have an easier time using a graphical application. I have found that GitHub Desktop is one of the best tools for this, since it is cross-platform and completely free. Some people prefer GitKraken, but I find that it tries too hard to push its paid features, and distracts you from what is actually important. You can find GitHub desktop downloads [here](https://desktop.github.com/download/) or, on Linux, you can install from Flathub.
GitHub is a website built around Git, a powerful version control tool. Therefore, you must also have Git installed. You can find installation instructions for your operating system [here](https://git-scm.com/downloads).
## Basic Git Concepts
With everything installed, we can start with some basic concepts. Here we will discuss the major elements you will interact with while using Git. Some you will already be familiar with just from using your computer or other versioned tools, but some will be more foreign.
### The Repository
A Git repository, commonly called a repo, is the top-level folder containing all other folders and files for your project. There is not one single right way to use a repository, but we'll get started with a basic rule of thumb: one repository corresponds to one product. Here are some examples of what might constitute a repository:
- A circuit board project containing all schematics, board layout files, gerbers, SPICE simulations, and other exported files
- A mechanical project containing a top-level assembly, all part files, and a folder with mesh exports
- A software project containing code, build files, and any files required to build the project
It might take some getting used to to figure out exactly when a new repository is justified as opposed to just making a new folder inside an existing repository. There are no strict rules, but you'll figure out what works best for you.
Regardless of where you decide to draw the lines, the purpose of the repository is the same: to group files and sub-folders into a single top-level folder, where all changes are tracked and versioned.
Git is a "distributed version control system", which means that the repository has a copy online (GitHub) and a copy on your computer. This means that if something were to happen to your computer, you can restore everything from the online copy, and if something were to happen to the online copy, you could restore it from your computer. Therefore, Git is very robust to data loss. Since you are working entirely off of files on your computer, you don't even need an internet connection to continue to do work or for Git to track your changes. The only time you need internet is when you want to get new commits from the online copy (pulling changes) or when you want to copy your changes from your computer to the online repo (pushing changes).
### Commits
A commit is a tracked set of changes. Think about it like a checkpoint for your project, like how in Google docs, where you can see previous versions go back to them, and see who made the changes. A commit in Git is much more powerful, however. While in Google docs, the "versions" are created automatically, in Git, you decide what constitutes a version.
Each commit will contain something called a diff. The diff is the set of additions, deletions, and modifications within a repository. Essentially, it is the changes from one version to the next. These changes can be as small as a single character in a single file, or as big as the deletion of every file in the repository or adding hundreds of new files. A good rule of thumb is to keep your commits complete, yet self-contained. For example, if you are experimenting with a new fin design on a rocket, rather than making a commit for each tiny change, a complete commit would be the rocket after the new fin design is finished. If you are doing multiple iterations of the design, each iteration would be its own commit. Additionally, it probably doesn't make sense to have a new nose cone design *and* a new fin design in the same commit, as you wouldn't be able to undo one without undoing both, hence the importance of keeping commits self-contained.
### Branches
Branches are one feature of Git that you probably would not be familiar if you haven't used a version control tool before. Most tools that let you go back to previous versions in a linear manner. With Git, changes can be made in parallel, and brought back together in the future. To enable this, a tool called a branch is used. I highly recommend reading [3.1 Git Branching - Branches in a Nutshell](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell) to get a stronger understanding of what branches are and how to use them.
A branch is simply a series of commits, but the important distinction is that you can start a branch from any commit, and multiple branches can start from the same commit. This enables parallel, non-destructive editing. So if you make a mistake on a branch, it won't affect the main line of development.
Branches are typically broken up into two or three categories. First, the main or master branch. This is the main line of development, where the primary goal should be to have the latest working version of all features. Work should never be done directly on the main branch, as adding a bad commit could ruin other people's work. This brings us to development branches. Development branches are where most work should be done, and they will be dedicated to a specific task. For example, you may have a development branch for designing a schematic for an individual circuit, or for adding a specific feature to a program. Sometimes you may want to make a branch off of a development branch for an experimental change. This would be called a topic branch. I find that topic branches make things too complicated and hard to follow, so I tend to avoid them where possible.
![](https://git-scm.com/images/about/branches@2x.png)
## Workflows
Now that we understand some basic terms, lets look at how they fit together.