Git Workflow Guide¶

Following these practices ensures smooth collaboration and maintains a clean project history.

Repository Structure¶

main: Primary development branch, always stable
feature/: Feature development branches
fix/: Bug fix branches
docs/: Documentation update branches

Getting Started¶

1. Fork the Repository¶

Navigate to the EmbSec Kit repository
Click the "Fork" button
Select your namespace for the fork

2. Clone Your Fork¶

# Clone your fork
git clone https://gitlab.com/YOUR_USERNAME/kit.git embsec-kit
cd embsec-kit

# Add upstream remote
git remote add upstream https://gitlab.com/embsec/kit.git

# Verify remotes
git remote -v

3. Configure Git¶

# Set your identity
git config user.name "Your Name"
git config user.email "your.email@example.com"

# Enable helpful settings
git config pull.rebase true
git config fetch.prune true
git config diff.colorMoved zebra

Branch Workflow¶

Creating a Branch¶

Choose the appropriate branch type based on your work:

# Feature branch
git checkout -b feature/add-spi-support

# Bug fix branch  
git checkout -b fix/uart-buffer-overflow

# Documentation branch
git checkout -b docs/improve-api-reference

Branch Naming Conventions¶

feature/: New features or enhancements
feature/add-crypto-module
feature/improve-error-handling
fix/: Bug fixes
fix/memory-leak-in-uart
fix/gpio-interrupt-handler
docs/: Documentation updates
docs/update-installation-guide
docs/add-api-examples
test/: Test additions or improvements
test/add-spi-coverage
test/fix-flaky-timer-test
refactor/: Code refactoring
refactor/simplify-build-system
refactor/extract-common-functions

Commit Guidelines¶

Commit Message Format¶

Follow the conventional commits specification:

<type>(<scope>): <subject>

<body>

<footer>

Components¶

Type (required)¶

feat: New feature
fix: Bug fix
docs: Documentation only
style: Code style (formatting, whitespace)
refactor: Code change without new features or fixes
test: Adding or updating tests
build: Build system or dependencies
ci: CI/CD configuration
perf: Performance improvement
chore: Maintenance tasks

Scope (optional)¶

sdk: SDK library changes
labs: Lab exercises
build: Build system
ci: CI/CD pipeline
docs: Documentation

Subject (required)¶

Use imperative mood ("add" not "added")
Don't capitalize first letter
No period at the end
Limit to 50 characters

Body (optional)¶

Explain what and why, not how
Wrap at 72 characters
Separate from subject with blank line

Reference issues: Fixes: #123
Breaking changes: BREAKING CHANGE: description
Co-authors: Co-authored-by: Name <email>

Commit Examples¶

# Simple commit
git commit -m "fix(uart): correct baud rate calculation"

# Detailed commit
git commit -m "feat(sdk): add DMA support for SPI transfers

Implement DMA-based transfers for the SPI peripheral to improve
performance for large data transfers. The implementation supports
both TX and RX DMA channels with configurable buffer sizes.

- Add embsec_spi_dma_init() function
- Support circular and normal DMA modes
- Include DMA interrupt handlers
- Add transfer completion callbacks

Fixes: #89"

# Breaking change
git commit -m "refactor(api)!: rename GPIO functions for consistency

BREAKING CHANGE: GPIO API functions have been renamed to follow
the embsec_module_action naming convention. Update your code:

- gpio_init() -> embsec_gpio_init()
- gpio_read() -> embsec_gpio_read()
- gpio_write() -> embsec_gpio_write()"

Working with Your Branch¶

Keep Your Branch Updated¶

# Fetch latest changes from upstream
git fetch upstream

# Rebase your branch on latest main
git checkout feature/my-feature
git rebase upstream/main

# Alternative: merge upstream changes
git merge upstream/main

Organizing Commits¶

Keep your commit history clean:

# Interactive rebase to clean up commits
git rebase -i upstream/main

# Common operations:
# - squash: combine commits
# - reword: change commit message
# - drop: remove commit
# - reorder: change commit order

Example interactive rebase:

pick 1234567 feat(spi): add basic SPI driver
squash 2345678 fix typo in spi.c
squash 3456789 add missing header
pick 4567890 test(spi): add unit tests
reword 5678901 docs(spi): document API

Stashing Changes¶

Save work in progress without committing:

# Stash current changes
git stash push -m "WIP: debugging SPI issue"

# List stashes
git stash list

# Apply latest stash
git stash pop

# Apply specific stash
git stash apply stash@{1}

Creating a Merge Request¶

1. Push Your Branch¶

# Push to your fork
git push origin feature/my-feature

# If rebased, may need force push
git push --force-with-lease origin feature/my-feature

2. Create the MR¶

Go to your fork on GitLab
Click "Create merge request"
Fill in the MR template:

## Description
Brief description of changes and why they're needed.

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that breaks existing functionality)
- [ ] Documentation update

## Testing

- [ ] All tests pass locally
- [ ] New tests added for new functionality
- [ ] Tested on hardware (if applicable)

## Checklist

- [ ] Code follows project style guidelines
- [ ] Self-review of code performed
- [ ] Documentation updated
- [ ] No new warnings introduced
- [ ] Changes are backwards compatible

## Related Issues
Fixes: #123
Related: #456

3. MR Best Practices¶

Title: Clear and descriptive
Description: Explain what and why
Small changes: Keep MRs focused and reviewable
Tests: Include tests for new functionality
Documentation: Update relevant docs
Screenshots: Include for UI changes

Code Review Process¶

For Authors¶

Respond to feedback: Address all review comments
Update commits: Use fixup commits or rebase
Re-request review: After making changes
Be patient: Reviews take time
Be receptive: Accept constructive criticism

For Reviewers¶

Be constructive: Suggest improvements
Be specific: Reference exact lines
Be timely: Review within 48 hours
Test locally: For complex changes
Approve explicitly: When satisfied

Review Comments¶

Use conventional prefixes:

MUST: Required change
SHOULD: Strongly recommended
CONSIDER: Suggestion to think about
NITPICK: Minor style issue
QUESTION: Seeking clarification

Example:

MUST: Check return value of embsec_uart_init() for errors

CONSIDER: Extract this logic into a helper function for reuse

NITPICK: Extra blank line here

Handling Conflicts¶

Merge Conflicts¶

# Update your branch
git fetch upstream
git rebase upstream/main

# If conflicts occur
# 1. Fix conflicts in affected files
# 2. Stage resolved files
git add <resolved-files>

# 3. Continue rebase
git rebase --continue

# Or abort if needed
git rebase --abort

Conflict Resolution Tips¶

Understand both changes
Test after resolution
Preserve functionality from both sides
When in doubt, ask for help

Advanced Git Tips¶

Useful Aliases¶

Add to ~/.gitconfig:

[alias]
    # Shortened commands
    co = checkout
    br = branch
    ci = commit
    st = status

    # Helpful workflows
    unstage = reset HEAD --
    last = log -1 HEAD
    visual = !gitk

    # Pretty log
    lg = log --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit

    # Show files in commit
    show-files = diff-tree --no-commit-id --name-only -r

Useful Commands¶

# Find commit that introduced bug
git bisect start
git bisect bad HEAD
git bisect good v1.0.0

# Search commit messages
git log --grep="uart"

# Search code changes
git log -S"embsec_uart_init"

# Show who changed what
git blame src/uart.c

# List branches by recent activity
git for-each-ref --sort=-committerdate refs/heads/

Troubleshooting¶

Common Issues¶

Pushed to wrong branch¶

# Create correct branch from current state
git branch feature/correct-name

# Reset original branch
git checkout main
git reset --hard upstream/main

# Push correct branch
git checkout feature/correct-name
git push origin feature/correct-name

Need to undo last commit¶

# Keep changes, undo commit
git reset --soft HEAD~1

# Discard changes and commit
git reset --hard HEAD~1

Accidentally committed to main¶

# Create branch with current changes
git branch feature/my-feature

# Reset main to upstream
git checkout main
git reset --hard upstream/main

# Continue on feature branch
git checkout feature/my-feature

Resources¶

Questions?¶

If you encounter issues:

Check this guide
Search existing issues/MRs
Ask in the MR discussion
Create an issue for persistent problems