Merge pull request #37 from Hyper-Unearthing/improve/post

Improve/post

Author: billybonks

_layouts/post.html

@@ -2,8 +2,26 @@
 title: support
 layout: default
 ---
+
 <div class="post-container">
-  <div class="post">
-    {{content}}
-  </div>
-</div>
+    <div class="post">
+        {{content}}
+        <script
+            src="https://giscus.app/client.js"
+            data-repo="Hyper-Unearthing/hyper-unearthing.github.io"
+            data-repo-id="R_kgDOMX5WrQ"
+            data-category="Blog"
+            data-category-id="DIC_kwDOMX5Wrc4CujwF"
+            data-mapping="pathname"
+            data-strict="0"
+            data-reactions-enabled="1"
+            data-emit-metadata="0"
+            data-input-position="top"
+            data-theme="catppuccin_mocha"
+            data-lang="en"
+            data-loading="lazy"
+            crossorigin="anonymous"
+            async
+        ></script>
+    </div>
+</div>

_posts/2025-08-14-commits.md

@@ -6,42 +6,30 @@ date: 2025-08-14 10:00:00 +0800
 
 # Commit History Best Practices
 
-A commit history is a record of changes that you made to your codebase. If you want to understand why you or someone on your team made a particular change to the codebase, having a well-written history will help you along that journey.
+Have you ever found yourself looking at code you wrote 6 months ago wondering why you did it that way? A well-crafted commit history transforms your repository into a comprehensive story of your codebase, where the purpose of every change is understood. In the rest of this blog post I wish to share best practices to achieve this outcome.
 
 ## Single Logical Changes
 
-Every commit should represent a single change that you want to make to the codebase. You may need to make many changes to achieve your goal, and this is what we colloquially know as merge requests or pull requests; I will refer to it as a collection of commits.
+Every commit should represent a single change that you want to make to the codebase. In order to reach a certain objective many changes may need to be made; this is what many know as merge or pull requests; I will refer to it as a collection of commits.
 
-When requesting to merge a collection of commits, each commit should represent a single logical step towards your goal. For example:
+For example, "Adding a tertiary styled button". In order for that to be done, we need to generalize the existing button styles, so that they can be extended and have the color changed. This change would be broken down into two logical steps.
 
-In order to build my feature, I need to refactor some code. Your first logical step is the refactor. The second step is building out your feature. Doing this allows you to easily backport your refactor into master while you continue on your feature. If the feature is small, it helps reviewers easily understand what impact they should be looking out for.
+- First refactor the button code,
+- Second implement your new button.
 
-## Clear Commit Summaries
+## Clear Commit Subject Lines
 
-A commit summary should clearly state how the system changes once this commit is applied. Think of expaining WHAT in less then x amount of characters
+A commit subject line should clearly state how the system changes once this commit is applied. Think of explaining WHAT in less than x amount of characters
 
-**Good**: "button stays the same size when text changes"
-**Bad**: "designers complained about the button"
+Using our previous example:
 
-This makes it easy to understand when looking at the history what are the exact things that have happened to the codebase, making it easier for you to find what you want.
+> **Good**: "button now has API to specify background color"<br /><br /> **Bad**: "Need to refactor the button code for tertiary style"
 
-### Tagging commits
+In the good example it is clear how this commit changed the system, if I wanted to understand why the change was made that's what the commit body is for.
 
-By tagging it means using part of your allocated summary to encode information into your commit message. for example:
-- **refactor**: Changes the code but does not change any behaviour, no tests should be affected
-- **fix**: Changes a unintended behaviour
-- **feat**: Adds net new behaviour to the system
-- **cicd**: only updates build and tests pipelines
+## Meaningful commit body
 
-This makes it easy to see in the past month what kinds of activities did we perform, it also gives reviewers context what code to expect in a commit.
-
-If you decide to tag commits, ensure that you do not use vague or ambiguous tags for example "chore", this does not describe what the goal of a commit was, all it does it encapsulates developer emotion about the task at hand.
-
-## Meaningful Descriptions
-
-The description of a commit message should encapsulate your thoughts around what you did. For example, you may have added some CSS, but you did it in a rushed manner and feel like it can be improved. This is great context for someone in the future to understand why the code is bad and that there is no special thing they are missing.
-
-Some examples of good content for history:
+The body is your opportunity to explain WHY you made the change. Using the previous example "We needed to add this API to support tertiary style buttons" gives great context as to the reason for the change. It is also a great opportunity to explain other thoughts and considerations that went into the decision.
 
 - How the code can be improved
 - Any challenges you encountered while writing the code
@@ -51,39 +39,13 @@ Some examples of good content for history:
 
 Just as we apply style guides to our codebase, commits should follow a consistent format. As long as the content is meaningful, the format does not really matter. For example:
 
+- subject line < 50 chars
+- body < 72 chars (per line)
 
+## TLDR
 
-- summary < 50 chars
-- description < 72 chars (per line)
-- type of change: Enum(refact, fix, feat, cicd, burn)
-
-> &lt;type of change&gt;: &lt;summary&gt;
-<br />
-<br />
-&lt;description&gt;
-
-
-Here are two examples of recent commits.
-
-{% highlight ruby %}
-commit 6ad486c23b634f448feecda54eb976d38c401b80
-Author: billybonks <sebastienstettler@gmail.com>
-Date:   Wed Aug 13 16:16:30 2025 +0800
-
-    feat: add support for input groups
-
-    the css is kinda yolo and not the best can change :D!
-    does not handle the case where you can label both elements because it
-    requires a bunch more work. specifically how forms are made
-{% endhighlight %}
-
-{% highlight ruby %}
-commit e341fa8b2827994af2c57bdb1e1744c134c9befe
-Author: billybonks <sebastienstettler@gmail.com>
-Date:   Wed Aug 13 00:25:27 2025 +0800
+When selecting the changes to the commit to add ask yourself **Does this commit contain more than one change that can be separated?**
 
-    refactor: extract chart design from chart builder
+While writing the subject line, answer the question **How does the system change when my commit is merged?**
 
-    we will be deleting all the vega code in favour of the backend aggregation
-    but this code is still required
-{% endhighlight %}
+When adding the body, ask yourself **Why did I make this change, how could this change be better, why did I do it this way?**