Crafting Conventional Commits and Professional READMEs

1. The Art of the Commit Message: Conventional Commits

In the previous lesson, you wrote simple commit messages like "Initial commit." In a professional environment, messages must be more descriptive. They should explain not just what changed, but why it changed. To achieve this consistently across a team, a standard called Conventional Commits is widely used. It enforces a simple, structured format for every commit message.

This makes the project history highly readable and allows for the automatic generation of change logs.

The Structure of a Conventional Commit

As you saw in the video, a conventional commit message follows this template:

<type>[optional scope]: <description>

[optional body]

[optional footer]

Let's break down the components:

1. Type: A short noun that describes the category of change. This is mandatory.
2. Scope: (Optional) A noun specifying the part of the codebase affected (e.g., gpio, uart_driver, build).
3. Description: A short, imperative-mood summary of the change (e.g., "add," not "added" or "adds").
4. Body: (Optional) A longer explanation providing context. This is where you explain why you made the change. It's separated from the subject by a blank line.
5. Footer: (Optional) Used for referencing issue tracker IDs (e.g., Fixes: #42) or noting breaking changes.

Common Commit Types

To give you a practical vocabulary, here are the most common commit types you will use.

Here is a summary of the most essential types for quick reference:

Practice Exercise

Let's apply this. Imagine you are working on the layered LCD driver from our previous lesson. You discover and fix a bug where calling lcd_send_string() with a NULL pointer causes the microcontroller to crash.

How would you write the conventional commit message for this fix?

fix(lcd_driver): prevent hard fault on NULL string input

Added a null check at the beginning of the lcd_send_string function.
If a NULL pointer is passed, the function now returns immediately
without attempting to dereference the pointer, which previously caused
a hard fault.

2. Crafting a Professional README.md

Now that you can document your changes, let's document your project. The README.md file is the first thing anyone sees when they visit your repository on GitHub. It should quickly and clearly answer:

• What is this project?
• What hardware and software do I need to use it?
• How do I build and run it?
• What does it do?

A well-written README demonstrates professionalism and makes your work accessible.

Anatomy of a Firmware Project README

Let's adapt the structure from the video for a typical STM32 project. Your README should be a file named README.md in the root of your project directory and written using Markdown, a simple text-formatting syntax.

Here are the essential sections for your embedded project's README:

1. Project Title and Summary

   • A main heading (# My Project Title) followed by a short, one-paragraph summary of the project's purpose.

2. Key Features

   • A bulleted list of the main functionalities. (e.g., "- Blinks an LED at 1Hz", "- Dims LED brightness using PWM controlled by a potentiometer").

3. Hardware Requirements

   • Be specific!
     • MCU Board: e.g., STM32F103C8T6 "Blue Pill"
     • Programmer/Debugger: e.g., ST-Link V2
     • Peripherals: e.g., 16x2 I2C LCD, HC-SR04 Ultrasonic Sensor, TJA1050 CAN Transceiver.
     • Tools: e.g., Digital Multimeter, Logic Analyzer.

4. Software & Toolchain

   • IDE: e.g., STM32CubeIDE v1.14.0
   • Compiler: e.g., GCC Arm Embedded
   • Libraries/Frameworks: e.g., FreeRTOS v10.4.3 (if applicable)

5. Setup and Build Instructions

   • Provide clear, step-by-step instructions for a new user.
     1. Clone the repository: git clone <your-repo-url>
     2. Open STM32CubeIDE.
     3. File -> Import... -> General -> Existing Projects into Workspace.
     4. Select the cloned directory.
     5. Project -> Build All.

6. Usage / How it Works

   • Explain what the user should expect to see after flashing the firmware.
   • Example: "After flashing, the green LED on PC13 will start blinking. Connect a terminal to the UART (PA9/PA10) at 115200 baud to see a 'Hello, World!' message printed every second."

7. Project Structure (Optional but Recommended)

   • Briefly describe your layered architecture.
     • Src/main.c: Application entry point and main loop.
     • Drivers/lcd_driver/: Low-level driver for the I2C LCD.
     • App/: High-level application logic.

Conclusion

In this lesson, you've moved beyond the mechanics of Git to the art of professional communication. By adopting Conventional Commits and crafting high-quality READMEs, you ensure your work is understandable, maintainable, and impressive to others.

Key Takeaways:

• Conventional Commits provide a standardized format (type(scope): description) that makes your Git history clean, readable, and easy to parse.
• The commit type categorizes your change (e.g., feat, fix, refactor), while the body explains the why.
• A professional README.md is the front door to your project. It must clearly explain the project's purpose, requirements, and setup instructions.
• For embedded projects, a good README includes specific sections for Hardware Requirements, Toolchain, and Build Instructions.

These practices are non-negotiable in the professional world. Applying them consistently in your personal projects will build strong habits and a powerful portfolio.

Preview of the Next Lesson:

So far, we've focused on static documentation—code comments, commit messages, and READMEs. But how do we understand what our firmware is doing while it's running? In our next lesson, we will tackle "Implement a lightweight logging system for runtime diagnostics via UART." You will learn to send formatted debug messages from your STM32 to your computer, giving you a real-time window into your application's behavior.