3.1: Pull Request Workflow Instructions
Pull Request Workflow for AI Agents
Purpose of Pull Requests
Why PRs Are Mandatory for ASPICE:
- Human-in-the-Loop (HITL): Enforces human review before merge
- Traceability: Links code changes to requirements and issues
- Quality Gates: Automated checks (build, test, MISRA) before human review
- Audit Trail: PR history provides evidence for ASPICE assessments
Step-by-Step PR Workflow
1. Create Pull Request
Action: Open PR after pushing feature branch
GitHub Example:
# After pushing branch:
git push -u origin feature/ASPICE-1234-acc-controller
# Create PR via GitHub CLI (recommended for AI agents)
gh pr create \
--title "Implement ACC obstacle distance calculation [ASPICE-1234]" \
--body "$(cat <<'EOF'
## Summary
- Implemented ACC_GetObstacleDistance() function
- Implements [SWE-045-1] from requirements spec
- Generated 6 unit test cases (100% coverage)
## Changes
- **Added**: src/acc_controller.c (285 LOC)
- **Added**: include/acc_controller.h (45 LOC)
- **Added**: tests/test_acc_controller.cpp (180 LOC)
- **Modified**: docs/traceability_matrix.xlsx
## Traceability
- **Implements**: [SWE-045-1] Obstacle Distance Calculation (ASIL-B)
- **Issue**: ASPICE-1234
- **Requirements**: SRS Section 3.2.1
## Quality Metrics
- **MISRA C:2012**: 0 Required violations [PASS]
- **Unit Tests**: 6/6 passed [PASS]
- **Coverage**: 100% statement, 95% branch [PASS]
- **Build**: Success [PASS]
## Human Action Required
1. Review ASIL-B safety logic (lines 45-78)
2. Validate fail-safe behavior (sensor fault handling)
3. Approve traceability links
## Checklist
- [x] Code compiles without errors/warnings
- [x] Unit tests pass (100%)
- [x] MISRA compliance verified
- [x] Doxygen documentation complete
- [x] Traceability tags present (@implements)
- [ ] Human review completed (pending)
- [ ] Approved for merge (pending)
---
[AI] Generated by AI Implementation Agent | ASPICE SWE.3
EOF
)" \
--base main \
--head feature/ASPICE-1234-acc-controller \
--label "feat,swe3,asil-b" \
--assignee @senior_engineer \
--reviewer @safety_engineer
# Output:
# https://github.com/company/acc-ecu/pull/142
GitLab Example (via API):
import requests
def create_gitlab_pr(project_id, source_branch, target_branch, title, description):
"""
Create GitLab merge request via API
"""
gitlab_url = "https://gitlab.com/api/v4"
access_token = os.getenv("GITLAB_TOKEN")
payload = {
"source_branch": source_branch,
"target_branch": target_branch,
"title": title,
"description": description,
"labels": "feat,swe3,asil-b",
"assignee_ids": [123], # User ID of senior engineer
"reviewer_ids": [456], # User ID of safety engineer
}
response = requests.post(
f"{gitlab_url}/projects/{project_id}/merge_requests",
headers={"PRIVATE-TOKEN": access_token},
json=payload
)
if response.status_code == 201:
pr_url = response.json()["web_url"]
print(f"[PASS] PR created: {pr_url}")
return pr_url
else:
print(f"[FAIL] PR creation failed: {response.text}")
return None
# Usage
create_gitlab_pr(
project_id=42,
source_branch="feature/ASPICE-1234-acc-controller",
target_branch="main",
title="Implement ACC obstacle distance calculation [ASPICE-1234]",
description=pr_description_text
)
2. PR Description Template
Standard PR Description:
## Summary
[2-3 sentences: What was implemented/fixed, why, what requirement]
## Changes
- **Added**: [List new files]
- **Modified**: [List changed files]
- **Deleted**: [List removed files]
## Traceability
- **Implements**: [SWE-XXX-Y] Requirement description (ASIL level)
- **Issue**: ASPICE-1234
- **Requirements**: SRS Section X.Y.Z
## Quality Metrics
- **MISRA C:2012**: <violations count> Required, <violations count> Advisory
- **Unit Tests**: <passed>/<total> passed
- **Coverage**: <percentage>% statement, <percentage>% branch
- **Build**: Success/Failure
- **Static Analysis**: <issues count> issues
## Human Action Required
1. [Specific review task 1]
2. [Specific review task 2]
3. [Approval decision]
## Checklist
- [x] Code compiles without errors/warnings
- [x] Unit tests pass
- [x] MISRA compliance verified
- [x] Doxygen documentation complete
- [x] Traceability tags present
- [ ] Human review completed (pending)
- [ ] Approved for merge (pending)
---
[AI] Generated by <AI Agent Name> | ASPICE <Process>
3. CI/CD Pipeline Execution
Action: Wait for automated checks to complete
Typical CI/CD Pipeline (GitLab CI example):
# .gitlab-ci.yml
stages:
- build
- test
- analyze
- review_prep
build_job:
stage: build
script:
- make clean && make all
artifacts:
paths:
- build/firmware.elf
test_job:
stage: test
script:
- make test
- gcov src/*.c
coverage: '/Lines executed: (\d+\.\d+)%/'
artifacts:
paths:
- coverage_report.html
reports:
junit: test_results.xml
misra_check:
stage: analyze
script:
- cppcheck --addon=misra src/*.c 2> misra_report.xml
- python3 parse_misra.py misra_report.xml
artifacts:
paths:
- misra_report.xml
review_prep:
stage: review_prep
script:
- radon cc src/*.c --min B # Complexity analysis
- git diff main... > code_diff.patch
artifacts:
paths:
- code_diff.patch
- complexity_report.txt
Pipeline Status:
[PASS] build_job: Passed (35s)
[PASS] test_job: Passed (12s) - Coverage: 95.2%
[PASS] misra_check: Passed (8s) - 0 Required violations
[PASS] review_prep: Passed (5s)
Overall: [PASS] PASSED (60s total)
If Pipeline Fails:
[FAIL] test_job: Failed (12s) - 1 test failed
TC-SWE-045-1-1: Expected 5.0, got 5.12
Action:
1. Fix failing test (debug code or update test)
2. Commit fix to same branch
3. Pipeline re-runs automatically
4. Automated Review (Review Agent)
Action: AI Review Agent posts automated findings
Review Agent Comment (GitHub/GitLab):
## [AI] Automated Code Review
### Verdict: [WARN] **APPROVE WITH COMMENTS**
**Automated Checks**:
- [PASS] MISRA C:2012: 0 Required violations, 2 Advisory
- [PASS] Unit Tests: 6/6 passed
- [PASS] Coverage: 95.2% statement (target: 100%)
- [PASS] Build: Success
- [WARN] Complexity: 1 function >20 (SensorFusion_Kalman: 25)
**Traceability**: 100% (all functions have @implements tags)
**Non-Blocking Issues**:
1. Line 156 (can_driver.c): Function name abbreviation (CAN_ReadMsg → CAN_ReadMessage)
2. Line 203 (diagnostics.c): Variable name not descriptive (tmp → temporary_buffer)
3. Coverage gap: 4.8% (lines 145, 178, 203) - hardware-dependent code (justification OK)
**Recommendation**: [PASS] **APPROVE** (non-blocking issues, create follow-up ticket)
**Human Reviewer**: Please verify ASIL-B safety logic (lines 45-78)
---
*Generated by AI Review Agent | ASPICE SUP.2 Verification*
5. Human Review
Action: Wait for human reviewer approval
Human Review Process:
- Notification: Assigned reviewer receives email/Slack notification
- Review: Human examines code, automated reports, test results
- Decision: Approve, request changes, or reject
Review Outcomes:
Option A: Approved [PASS]
## Human Review: [PASS] **APPROVED**
**Reviewer**: @senior_engineer (John Doe)
**Date**: 2025-12-17
**Review Notes**:
- Code quality: Excellent (MISRA compliant, well-documented)
- Safety logic: Verified correct (sensor fault → safe state transition)
- Traceability: 100% (all requirements linked)
**Approved for merge**
Signed: John Doe
Option B: Request Changes [WARN]
## Human Review: [WARN] **REQUEST CHANGES**
**Reviewer**: @safety_engineer (Jane Smith)
**Date**: 2025-12-17
**Issues Found**:
1. **Line 67** (acc_controller.c): Fail-safe behavior incomplete
- Issue: Sensor fault only disables ACC, but brake command not released
- Fix: Add `CAN_SendBrakeCommand(BRAKE_RELEASE)` after ACC disable
- Severity: **CRITICAL** (ASIL-B safety requirement)
2. **Line 145** (acc_controller.c): Integer overflow not checked
- Issue: `distance_mm * 1000` may overflow uint16_t
- Fix: Cast to uint32_t before multiplication
- Severity: **MAJOR**
**Action Required**: Fix issues, resubmit for review
Signed: Jane Smith
Option C: Rejected [FAIL]
## Human Review: [FAIL] **REJECTED**
**Reviewer**: @architect (Bob Johnson)
**Date**: 2025-12-17
**Reason**: Architectural violation
- This PR introduces tight coupling between ACC_Controller and CAN_Driver
- Violates layered architecture (ACC should use abstract interface, not call CAN directly)
**Recommendation**: Refactor to use dependency injection (function pointers)
**Action**: Close PR, create new PR with corrected architecture
Signed: Bob Johnson
6. Address Review Comments
Action: Fix issues, push updates to same branch
If Changes Requested:
# Fix issues identified by human reviewer
# (edit files: src/acc_controller.c)
# Stage and commit fixes
git add src/acc_controller.c
git commit -m "fix(acc): Address review feedback [ASPICE-1234]
- Add brake release on ACC disable (safety fix)
- Fix integer overflow (cast to uint32_t)
Reviewed-by: @safety_engineer
Fixes: #142 (review comments)"
# Push to same branch (PR updates automatically)
git push origin feature/ASPICE-1234-acc-controller
# PR comment automatically added:
# "AI agent pushed 1 new commit (a7f8e32): fix(acc): Address review feedback"
CI/CD Re-Runs:
- Pipeline executes again automatically
- If passes → Human reviewer re-reviews
- If fails → Fix and repeat
7. Merge Pull Request
Action: Human approves and merges (AI cannot merge)
Merge Methods:
1. Merge Commit (preserves full history):
# GitHub/GitLab UI: Click "Merge" button
# Or via CLI:
gh pr merge 142 --merge
# Result: Merge commit created
# Commit graph:
# main: ... ─ M (merge commit)
# ╱
# feature: ... ─ A ─ B ─ C
2. Squash and Merge (clean history, recommended):
# GitHub/GitLab UI: Click "Squash and merge"
gh pr merge 142 --squash
# Result: All feature branch commits squashed into one
# Commit graph:
# main: ... ─ S (single squashed commit)
3. Rebase and Merge (linear history):
# GitHub/GitLab UI: Click "Rebase and merge"
gh pr merge 142 --rebase
# Result: Feature commits rebased onto main
# Commit graph:
# main: ... ─ A' ─ B' ─ C' (rebased commits)
Recommended: Squash and merge for AI-generated PRs (clean history, one commit per feature)
8. Post-Merge Actions
Action: Cleanup, close issue, notify stakeholders
Automatic Actions (GitHub/GitLab):
- Branch Deletion: Feature branch deleted automatically (optional setting)
- Issue Closure: Linked issue (ASPICE-1234) closed automatically
- Notifications: Stakeholders notified (PR merged, issue closed)
Manual Actions (AI agent):
# Delete local feature branch (cleanup)
git checkout main
git branch -D feature/ASPICE-1234-acc-controller
# Pull latest main (includes merged PR)
git pull origin main
# Verify merge
git log -1 --oneline
# Output: a7f8e32 feat(acc): Implement distance calculation [ASPICE-1234] (#142)
Update Traceability (if not automated):
# Update traceability matrix (link PR to requirement)
traceability_matrix.add_link(
requirement_id="SWE-045-1",
implementation="src/acc_controller.c:45-78",
test="tests/test_acc_controller.cpp:TC-SWE-045-1-1",
pr_number=142,
commit_hash="a7f8e32",
reviewed_by="@senior_engineer"
)
PR Best Practices
For AI Agents
1. Small, Focused PRs:
- [PASS] One feature per PR (e.g., one function, one requirement)
- [PASS] Target: fewer than 300 LOC per PR (faster review)
- [FAIL] Avoid mega-PRs (1000+ LOC, multiple features)
2. Complete PR Description:
- [PASS] Include summary, traceability, quality metrics
- [PASS] Specify human action required
- [PASS] Attach automated reports (MISRA, coverage)
3. Address Feedback Promptly:
- [PASS] Respond to review comments within 24 hours
- [PASS] Explain reasoning if disagreeing with feedback
- [PASS] Re-request review after fixing issues
4. Keep PR Updated:
- [PASS] Rebase on main if conflicts arise
- [PASS] Resolve merge conflicts promptly
- [PASS] Re-run tests after rebase
Summary
Pull Request Workflow Key Steps:
- Create PR:
gh pr createwith complete description, labels, reviewers - CI/CD: Wait for automated checks (build, test, MISRA)
- Automated Review: Review Agent posts findings
- Human Review: Wait for approval/feedback
- Address Feedback: Fix issues, push to same branch
- Merge: Human approves and merges (squash recommended)
- Cleanup: Delete branch, close issue, update traceability
HITL Gate: Human review is mandatory (ASPICE compliance)
PR Size: Target fewer than 300 LOC for fast review turnaround
Next: Testing Workflow (31.02) - CI/CD integration, test execution, reporting