Merge pull request #208 from sysprog21/git-best-practice

Enhance Git commit style

Author: jserv

CONTRIBUTING.md

@@ -791,7 +791,50 @@ to `memset()` structures with zero.  Non-zero `NULL` is for retro computing.
 
 ## Git Commit Style
 
-Clear and descriptive commit messages are crucial for maintaining a transparent history of changes and for facilitating effective debugging and tracking. Please adhere to the guidelines outlined in [How to Write a Git Commit Message](http://chris.beams.io/posts/git-commit/).
+Effective version control is critical to modern software development.
+Git's powerful features—such as granular commits, branching,
+and a versatile staging area—offer unparalleled flexibility.
+However, this flexibility can sometimes lead to disorganized commit histories and
+merge conflicts if not managed with clear, consistent practices.
+
+By committing often, writing clear messages, and adhering to a common workflow,
+developers can not only reduce the potential for errors but also simplify collaboration and future maintenance.
+We encourage every team to tailor these best practices to their specific needs while striving
+for a shared standard that promotes efficiency and code quality.
+
+Below are the detailed guidelines that build on these principles.
+* Group Related Changes Together
+  Each commit should encapsulate a single, coherent change.
+  e.g., if you are addressing two separate bugs, create two distinct commits.
+  This approach produces focused, small commits that simplify understanding, enable quick rollbacks,
+  and foster efficient peer reviews.
+  By taking advantage of Git’s staging area and selective file staging,
+  you can craft granular commits that make collaboration smoother and more transparent.
+* Commit Frequently
+  Making commits often ensures that your changes remain concise and logically grouped.
+  Frequent commits not only help maintain a clean history but also allow you to share your progress with your teammates regularly.
+  This regular sharing keeps everyone in sync,
+  minimizes merge conflicts, and promotes a collaborative environment where integration happens seamlessly.
+* Avoid Committing Work in Progress
+  Only commit code when a logical component is in a stable, ready-to-integrate state.
+  Break your feature's development into manageable segments that reach a functional milestone quickly,
+  so you can commit regularly without compromising quality.
+  If you feel the urge to commit merely to clear your working directory for actions like switching branches or pulling changes,
+  use Git's stash feature instead.
+  This practice helps maintain a stable repository and ensures that your team reviews well-tested, coherent code.
+* Test Your Code Before Committing
+  Before committing, ensure that your code has been thoroughly tested.
+  Rather than assuming your changes are ready, run comprehensive tests to confirm they work as intended without unintended side effects.
+  Testing is especially critical when sharing your code with others,
+  as it maintains the overall stability of the project and builds trust among collaborators.
+* Utilize Branches for Parallel Development
+  Branches are a powerful tool that enables developers to isolate different lines of work—whether you are developing new features,
+  fixing bugs, or exploring innovative ideas.
+  By using branches extensively, you can work on your tasks independently and merge only after careful review and testing.
+  This not only keeps the main branch stable but also encourages collaborative code reviews and a more organized integration process.
+
+Clear and descriptive commit messages are crucial for maintaining a transparent history of changes and for facilitating effective debugging and tracking.
+Please adhere to the guidelines outlined in [How to Write a Git Commit Message](http://chris.beams.io/posts/git-commit/).
 1. Separate the subject from the body with a blank line.
 2. Limit the subject line to 50 characters.
 3. Capitalize the subject line.
@@ -801,7 +844,6 @@ Clear and descriptive commit messages are crucial for maintaining a transparent
 7. Use the body to explain what and why, not how.
 
 An example (derived from Chris' blog post) looks like the following:
-
 ```text
 Summarize changes in around 50 characters or less
 
@@ -830,6 +872,34 @@ like this:
 Close #123
 ```
 
+Another illustration of effective practice.
+```text
+commit f1775422bb5a1aa6e79a685dfa7cb54a852b567b
+Author: Jim Huang <[email protected]>
+Date:   Mon Feb 24 13:08:32 2025 +0800
+
+    Introduce CPU architecture filtering in scheduler
+    
+    In environments with mixed CPU architectures, it is crucial to ensure
+    that an instance runs only on a host with a compatible CPU
+    type—preventing, for example, a RISC-V instance from being scheduled on
+    an Arm host.
+    
+    This new scheduler filter enforces that requirement by comparing an
+    instance's architecture against the host's allowed architectures. For
+    the libvirt driver, the host's guest capabilities are queried, and the
+    permitted architectures are recorded in the permitted_instances_types
+    list within the host's cpu_info dictionary.
+    
+    The filter systematically excludes hosts that do not support the
+    instance's CPU architecture. Additionally, RISC-V has been added to the
+    set of acceptable architectures for scheduling.
+    
+    Note that the CPU architecture filter is disabled by default.
+```
+
+The above is a clear, unformatted description provided in plain text.
+
 In addition, this project expects contributors to follow these additional rules:
 * If there is important, useful, or essential conversation or information,
   include a reference or copy it.

scripts/aspell-pws

@@ -332,3 +332,9 @@ SIGTERM
 SIGTRAP
 SIGUSR
 SIGWINCH
+risc
+mips
+riscv
+info
+cpu
+libvirt