🐙

Git & GitHub Workflow

Team Guidelines · Version 4.0 · Last Updated: October 2025

Purpose
Repository Naming & Structure
Branching Model
Roles & Responsibilities
Versioning & Releases
Git Submodules
Best Practices
Security & Access Matrix

1. Purpose

This document defines the standard Git & GitHub workflow for all firmware teams. It ensures code integrity, traceability, and predictable release management across projects by clearly defining repository structure, branching and merging strategies, and role-based responsibilities (Admin / Manager / Developer).

2. Repository Naming and Structure

Naming Convention

Type	Naming Format	Example
Firmware source code	`projectname-fw`	`sensorhub-fw`
Documentation	`projectname-doc`	`sensorhub-doc`
Shared library	`libname-fwlib`	`motorctrl-fwlib`
Test or simulation	`projectname-test`	`sensorhub-test`

📋 Important: All documentation (system design, field test logs, hardware specs) lives in a dedicated projectname-doc repository. Do not commit binaries, SDKs, build artifacts, or secrets.

Repository Folder Layout

✅ Standard Project Structure

projectname-fw/
│
├── docs/                # Developer-facing notes
├── src/                 # Firmware source
├── include/             # Headers
├── build/               # Build scripts (no compiled outputs)
├── tools/               # Flashing or analysis utilities
├── tests/               # Unit/integration tests
├── .gitignore
├── README.md
├── LICENSE
└── CHANGELOG.md

3. Branching Model Overview

Flow: feature / bugfix branches → development → staging → production

Main Branches

Branch	Purpose	Access
development	Active development branch. All new work starts here.	All Developers
staging	Integration and field-testing branch.	Managers only
production	Stable, released firmware in production.	Admins & Managers

Developer Branches

📌

All development must have a basis (work item, user story, feature or task)

⏱️

Feature branches should be short-lived (aim to merge within two weeks)

👤

Each developer should have only one active branch assigned to them where possible

Branch Naming Examples

feature/feature-name
bugfix/ISSUE-123
hotfix/critical-security-patch
docs/update-api-documentation

⚠️ Note on Master: Do NOT push directly to master unless you are a repository maintainer. Maintain strict protection rules.

4. Roles, Responsibilities & Permissions

🔐 Admin

Responsible for overall integrity of repositories

Responsibilities:

Create and configure repositories
Enforce branch protections
Manage teams and CI/CD pipelines
Approve merges to production
Maintain security policies (2FA, signed commits)
Ensure no secrets in repos

👔 Manager / Maintainer

Acts as technical lead for the project

Responsibilities:

Review PRs to development
Integrate stable work into staging
Maintain changelogs
Supervise testing cycles
Tag releases
Coordinate with developers

💻 Developer

Builds, tests, and submits code via pull requests

Typical Workflow:

Developer Workflow

git checkout -b feature/add-usb-bootloader

# work locally, commit often

git fetch origin
git merge origin/development
git push origin feature/add-usb-bootloader

# open PR -> development

5. Versioning & Releases

Semantic Versioning

Use semantic versioning: MAJOR.MINOR.PATCH (e.g., v2.1.0)

v2.1.0

2 MAJOR

Breaking changes, incompatible API changes

1 MINOR

New features, backward compatible

0 PATCH

Bug fixes, backward compatible

Release Process

Creating a Release

git tag -a v2.1.0 -m "Release v2.1.0 – New USB stack"
git push origin v2.1.0

📦 Release Artifacts: Attach binaries in GitHub Releases (not in repo), and update CHANGELOG.md with release notes.

CHANGELOG.md Format

✅ CHANGELOG.md Example

# Changelog

## [2.1.0] - 2025-11-06

### Added
- New USB bootloader support
- Over-the-air (OTA) update capability
- Temperature calibration interface

### Changed
- Improved WiFi reconnection logic
- Optimized power consumption in sleep mode

### Fixed
- Sensor timeout issue in low-power mode
- Memory leak in MQTT client

## [2.0.0] - 2025-10-15

### Breaking Changes
- Changed API for sensor configuration
- Removed deprecated functions from v1.x

### Added
- RTOS support with FreeRTOS
- Multi-sensor support

6. Git Submodules

Use submodules for shared libraries intended for reuse across projects. This keeps common code synchronized and version-controlled.

Adding a Submodule

Add Shared Library

# Add submodule to your project
git submodule add https://github.com/yourorg/motorctrl-fwlib lib/motorctrl

# Commit the submodule reference
git commit -m "Add motorctrl library as submodule"

Cloning with Submodules

Clone Project with Submodules

# Option 1: Clone and init submodules in one command
git clone --recurse-submodules https://github.com/yourorg/project-fw

# Option 2: Clone first, then init submodules
git clone https://github.com/yourorg/project-fw
cd project-fw
git submodule init
git submodule update

Updating Submodules

Update to Latest Submodule Version

# Enter submodule directory
cd lib/motorctrl

# Pull latest changes
git pull origin main

# Return to main project
cd ../..

# Commit the submodule update
git add lib/motorctrl
git commit -m "Update motorctrl library to v1.5.0"
git push

💡 Important: Update the submodule and commit the change in the container repo when the submodule HEAD changes. This ensures everyone gets the correct version.

7. Best Practices & Common Pitfalls

✅ Do's

✅

Keep development clean and buildable

Every commit to development should compile and pass basic tests

✅

Use .gitignore aggressively

Exclude build outputs, IDE files, OS-specific files, and temporary files

✅

Write atomic commits and meaningful messages

Each commit should represent one logical change with clear description

✅

Pull before push

Always fetch and merge latest changes before pushing your work

✅

Review before merging

All code must be reviewed by at least one other team member

🚫 Don'ts

🚫

Don't force-push shared branches

Force pushing rewrites history and breaks collaboration

🚫

Don't commit binaries, SDKs, or secrets

Use .gitignore and environment variables for configuration

🚫

Don't merge unreviewed or untested code

All PRs must pass review and CI/CD checks before merging

🚫

Don't push directly to protected branches

Use pull requests for all changes to development, staging, and production

.gitignore Template

✅ Firmware .gitignore

# Build outputs
build/
*.bin
*.hex
*.elf
*.map

# IDE files
.vscode/
.idea/
*.code-workspace

# OS files
.DS_Store
Thumbs.db

# Temporary files
*.tmp
*.log
*.swp

# Secrets
secrets.h
config_local.h
*.key
*.pem

8. Security & Access Matrix

Role	Create Repos	Merge to Dev	Merge to Staging	Merge to Production	Tag Releases	Manage Access
Admin	✅	⚠️	✅	✅	✅	✅
Manager	❌	✅	✅	✅ (with Admin)	✅	❌
Developer	❌	✅ (via PR)	❌	❌	❌	❌

Security Best Practices

🔐

Enable 2FA

Require two-factor authentication for all team members

✍️

Signed Commits

Use GPG signing to verify commit authenticity

🔒

No Secrets in Repos

Use environment variables or secret management tools

🛡️

Branch Protection Rules

Require PR reviews, passing CI, and up-to-date branches

🎯 Quick Reference: Developer Daily Workflow

Start Daygit pull origin development

Create Branchgit checkout -b feature/my-work

Developgit add . && git commit -m "message"

Stay Updatedgit merge origin/development

Push & PRgit push -u origin feature/my-work

← Back to Documentation

Firmware Guide →Project Development →

Layered Systems

Git & GitHub Workflow

Contents

1. Purpose

2. Repository Naming and Structure

Naming Convention

Repository Folder Layout

3. Branching Model Overview

Main Branches

Developer Branches

4. Roles, Responsibilities & Permissions

🔐 Admin

Responsibilities:

👔 Manager / Maintainer

Responsibilities:

💻 Developer

Typical Workflow:

5. Versioning & Releases

Semantic Versioning

Release Process

CHANGELOG.md Format

6. Git Submodules

Adding a Submodule

Cloning with Submodules

Updating Submodules

7. Best Practices & Common Pitfalls

✅ Do's

🚫 Don'ts

.gitignore Template

8. Security & Access Matrix

Security Best Practices

🎯 Quick Reference: Developer Daily Workflow