Skip to content

Commit 993d3cf

Browse files
author
Bryan Howard
committed
Enhance bug tracking with GitHub Issues integration and automation
- Add comprehensive GitHub sync process documentation - Implement Python automation script for bidirectional sync - Create GitHub Actions workflow for automated synchronization - Add label setup scripts for proper issue categorization - Update existing bug with GitHub issue #35 reference - Enable rich GitHub issue formatting with direct file links Features: - Manual and automated sync between docs/bugs/ and GitHub Issues - Smart labeling based on priority and component metadata - Direct clickable links from GitHub issues to documentation files - Validation tools for sync status monitoring 🤖 Generated with [Claude Code](https://claude.ai/code)
1 parent f1a6e75 commit 993d3cf

File tree

7 files changed

+628
-3
lines changed

7 files changed

+628
-3
lines changed

‎.github/workflows/bug-sync.yml‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
name: Bug Sync Automation
2+
3+
on:
4+
push:
5+
paths:
6+
- 'docs/bugs/**'
7+
branches:
8+
- main
9+
- feature/*
10+
issues:
11+
types: [opened, edited, closed, labeled]
12+
13+
jobs:
14+
sync-bugs:
15+
if: contains(github.event.issue.labels.*.name, 'bug') || github.event_name == 'push'
16+
runs-on: ubuntu-latest
17+
18+
permissions:
19+
issues: write
20+
contents: write
21+
pull-requests: write
22+
23+
steps:
24+
- name: Checkout repository
25+
uses: actions/checkout@v4
26+
with:
27+
token: ${{ secrets.GITHUB_TOKEN }}
28+
29+
- name: Setup Python
30+
uses: actions/setup-python@v4
31+
with:
32+
python-version: '3.9'
33+
34+
- name: Install GitHub CLI
35+
run: |
36+
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
37+
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
38+
sudo apt update
39+
sudo apt install gh
40+
41+
- name: Configure GitHub CLI
42+
run: |
43+
echo "${{ secrets.GITHUB_TOKEN }}" | gh auth login --with-token
44+
45+
- name: Sync new local bugs to GitHub
46+
if: github.event_name == 'push'
47+
run: |
48+
# Check for new bug files in the push
49+
git diff --name-only ${{ github.event.before }} ${{ github.event.after }} | grep "^docs/bugs/BUG-.*\.md$" || exit 0
50+
51+
# Run sync automation
52+
python scripts/bug-sync-automation.py --sync-to-github
53+
54+
# Commit any updates to bug files
55+
git config --local user.email "[email protected]"
56+
git config --local user.name "GitHub Action"
57+
58+
if git diff --quiet; then
59+
echo "No changes to commit"
60+
else
61+
git add docs/bugs/
62+
git commit -m "Auto-sync: Update bug files with GitHub issue references
63+
64+
🤖 Generated with GitHub Actions"
65+
git push
66+
fi
67+
68+
- name: Update local bug file when GitHub issue changes
69+
if: github.event_name == 'issues'
70+
run: |
71+
# Extract bug ID from issue title
72+
ISSUE_TITLE="${{ github.event.issue.title }}"
73+
BUG_ID=$(echo "$ISSUE_TITLE" | grep -o "BUG-[0-9]\{4\}-[0-9]\{2\}-[0-9]\{2\}-[0-9]\+" || echo "")
74+
75+
if [ -z "$BUG_ID" ]; then
76+
echo "No bug ID found in issue title: $ISSUE_TITLE"
77+
exit 0
78+
fi
79+
80+
# Find corresponding local bug file
81+
BUG_FILE=$(find docs/bugs/ -name "$BUG_ID-*.md" | head -1)
82+
83+
if [ -z "$BUG_FILE" ]; then
84+
echo "No local bug file found for $BUG_ID"
85+
exit 0
86+
fi
87+
88+
echo "Updating $BUG_FILE based on GitHub issue #${{ github.event.issue.number }}"
89+
90+
# Update Last Sync date in the bug file
91+
TODAY=$(date '+%Y-%m-%d')
92+
sed -i "s/\*\*Last Sync\*\*:.*/\*\*Last Sync\*\*: $TODAY/" "$BUG_FILE"
93+
94+
# If issue was closed, add comment about GitHub status
95+
if [ "${{ github.event.action }}" = "closed" ]; then
96+
echo "" >> "$BUG_FILE"
97+
echo "**GitHub Update ($TODAY)**: Issue #${{ github.event.issue.number }} was closed on GitHub" >> "$BUG_FILE"
98+
fi
99+
100+
# Commit changes
101+
git config --local user.email "[email protected]"
102+
git config --local user.name "GitHub Action"
103+
104+
if git diff --quiet; then
105+
echo "No changes to commit"
106+
else
107+
git add "$BUG_FILE"
108+
git commit -m "Auto-sync: Update $BUG_ID from GitHub issue #${{ github.event.issue.number }}
109+
110+
🤖 Generated with GitHub Actions"
111+
git push
112+
fi
113+
114+
- name: Validate bug sync status
115+
run: |
116+
python scripts/bug-sync-automation.py --validate

‎docs/bugs/BUG-2025-01-001-reroute-execution-data-loss.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,10 @@
33
**Status**: Open
44
**Priority**: High
55
**Component**: Execution Engine, Reroute Nodes
6+
**GitHub Issue**: #35
67
**Reporter**: Development Team
78
**Date**: 2025-01-16
9+
**Last Sync**: 2025-01-16
810

911
## Summary
1012

‎docs/bugs/README.md‎

Lines changed: 28 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,14 @@
22

33
This directory contains bug reports and tracking for PyFlowGraph issues discovered during development and testing.
44

5+
## GitHub Integration
6+
7+
We maintain bugs in two synchronized locations:
8+
- **Local Documentation**: `docs/bugs/` - Detailed technical documentation (this directory)
9+
- **GitHub Issues**: Project issue tracker - Community visibility and collaboration
10+
11+
See [GitHub Sync Process](github-sync-process.md) for complete synchronization workflow.
12+
513
## Bug Report Format
614

715
Each bug should be documented with:
@@ -10,6 +18,7 @@ Each bug should be documented with:
1018
- **Status**: Open, In Progress, Fixed, Closed
1119
- **Priority**: Critical, High, Medium, Low
1220
- **Component**: Affected system/module
21+
- **GitHub Issue**: Link to corresponding GitHub issue
1322
- **Description**: Detailed issue description
1423
- **Steps to Reproduce**: Clear reproduction steps
1524
- **Expected Behavior**: What should happen
@@ -19,9 +28,25 @@ Each bug should be documented with:
1928

2029
## Current Bug List
2130

22-
| ID | Title | Status | Priority | Component |
23-
|---|---|---|---|---|
24-
| BUG-2025-01-001 | Reroute nodes return None in execution | Open | High | Execution Engine |
31+
| ID | Title | Status | Priority | Component | GitHub Issue |
32+
|---|---|---|---|---|---|
33+
| BUG-2025-01-001 | Reroute nodes return None in execution | Open | High | Execution Engine | [#35](https://github.com/bhowiebkr/PyFlowGraph/issues/35) |
34+
35+
## Quick Actions
36+
37+
### Create GitHub Issue for Existing Bug
38+
```bash
39+
# Example: Create issue for BUG-2025-01-001
40+
gh issue create --title "BUG-2025-01-001: Reroute nodes return None in execution" \
41+
--body "Detailed technical information: docs/bugs/BUG-2025-01-001-reroute-execution-data-loss.md" \
42+
--label "bug,high-priority,execution"
43+
```
44+
45+
### Sync Local Bug to GitHub
46+
1. Update local bug file with latest information
47+
2. Create or update GitHub issue
48+
3. Add GitHub issue number to local bug file header
49+
4. Commit changes to git
2550

2651
## Bug Categories
2752

‎docs/bugs/github-sync-process.md‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
# GitHub Issues Sync Process
2+
3+
This document outlines the process for maintaining bidirectional synchronization between local bug documentation in `docs/bugs/` and GitHub Issues.
4+
5+
## Overview
6+
7+
We maintain bugs in two places:
8+
1. **Local Documentation**: `docs/bugs/` - Detailed technical documentation
9+
2. **GitHub Issues**: Project issue tracker - Community visibility and collaboration
10+
11+
## Manual Sync Process
12+
13+
### Creating a New Bug Report
14+
15+
#### Option A: Start Locally
16+
1. Create detailed bug report in `docs/bugs/BUG-YYYY-MM-DD-###-title.md`
17+
2. Update `docs/bugs/README.md` bug list table
18+
3. Create corresponding GitHub Issue:
19+
```bash
20+
gh issue create --title "BUG-YYYY-MM-DD-###: Title" \
21+
--body "See docs/bugs/BUG-YYYY-MM-DD-###-title.md for detailed technical information" \
22+
--label "bug,documentation"
23+
```
24+
4. Add GitHub issue number to local bug file header
25+
5. Commit changes to git
26+
27+
#### Option B: Start with GitHub Issue
28+
1. Create GitHub Issue with bug label
29+
2. Note the issue number (e.g., #42)
30+
3. Create local bug file: `docs/bugs/BUG-YYYY-MM-DD-###-title.md`
31+
4. Include GitHub issue reference in header
32+
5. Update `docs/bugs/README.md` bug list table
33+
6. Commit changes to git
34+
35+
### Bug File Header Format
36+
37+
Add GitHub sync information to each bug file:
38+
39+
```markdown
40+
# BUG-YYYY-MM-DD-###: Title
41+
42+
**Status**: Open
43+
**Priority**: High
44+
**Component**: Component Name
45+
**GitHub Issue**: #42
46+
**Created**: YYYY-MM-DD
47+
**Last Sync**: YYYY-MM-DD
48+
```
49+
50+
### Status Synchronization
51+
52+
| Local Status | GitHub Status | Action |
53+
|---|---|---|
54+
| Open | Open | No action needed |
55+
| In Progress | Open + "in progress" label | Add label to GitHub |
56+
| Fixed | Closed + "fixed" label | Close issue with comment |
57+
| Closed | Closed | No action needed |
58+
59+
### Update Process
60+
61+
#### When Updating Local Bug File
62+
1. Make changes to local markdown file
63+
2. Update "Last Sync" date in header
64+
3. Add comment to GitHub Issue:
65+
```bash
66+
gh issue comment 42 --body "Updated technical documentation in docs/bugs/BUG-YYYY-MM-DD-###-title.md"
67+
```
68+
69+
#### When GitHub Issue Updated
70+
1. Review GitHub Issue changes
71+
2. Update corresponding local bug file
72+
3. Update "Last Sync" date
73+
4. Commit changes to git
74+
75+
## GitHub CLI Commands Reference
76+
77+
### Common Operations
78+
```bash
79+
# Create issue from local bug
80+
gh issue create --title "BUG-2025-01-001: Reroute nodes return None" \
81+
--body "Detailed technical info: docs/bugs/BUG-2025-01-001-reroute-execution-data-loss.md" \
82+
--label "bug,high-priority,execution"
83+
84+
# List all bug issues
85+
gh issue list --label "bug"
86+
87+
# Close issue as fixed
88+
gh issue close 42 --comment "Fixed in commit abc123. See updated docs/bugs/ for details."
89+
90+
# Add labels
91+
gh issue edit 42 --add-label "in-progress"
92+
93+
# View issue details
94+
gh issue view 42
95+
```
96+
97+
## Automation Options
98+
99+
### GitHub Actions Workflow (Recommended)
100+
101+
Create `.github/workflows/bug-sync.yml` to automate:
102+
- Create GitHub Issue when new bug file added to docs/bugs/
103+
- Update issue labels when bug status changes
104+
- Comment on issues when bug files updated
105+
106+
### Manual Scripts
107+
108+
Create utility scripts in `scripts/` directory:
109+
- `sync-bugs-to-github.py` - Push local changes to GitHub
110+
- `sync-bugs-from-github.py` - Pull GitHub updates to local files
111+
- `validate-bug-sync.py` - Check sync status
112+
113+
## Bug Labels
114+
115+
Standard GitHub labels for bug categorization:
116+
117+
| Label | Description | Usage |
118+
|---|---|---|
119+
| `bug` | Bug report | All bug issues |
120+
| `critical` | Critical priority | System-breaking bugs |
121+
| `high-priority` | High priority | Major functionality issues |
122+
| `medium-priority` | Medium priority | Minor functionality issues |
123+
| `low-priority` | Low priority | Cosmetic/enhancement bugs |
124+
| `execution` | Execution engine | Graph execution bugs |
125+
| `ui` | User interface | UI/UX bugs |
126+
| `file-ops` | File operations | File I/O bugs |
127+
| `node-system` | Node system | Node creation/editing bugs |
128+
| `undo-redo` | Undo/redo | Command system bugs |
129+
| `performance` | Performance | Speed/memory bugs |
130+
| `in-progress` | Work in progress | Currently being worked on |
131+
| `needs-repro` | Needs reproduction | Cannot reproduce issue |
132+
| `duplicate` | Duplicate issue | Duplicate of another issue |
133+
134+
## Workflow Examples
135+
136+
### Example 1: New Bug Discovery
137+
1. Discover reroute node execution bug during testing
138+
2. Create `docs/bugs/BUG-2025-01-002-new-issue.md` with full details
139+
3. Run: `gh issue create --title "BUG-2025-01-002: New Issue" --body "See docs/bugs/BUG-2025-01-002-new-issue.md" --label "bug,high-priority"`
140+
4. Add GitHub issue number to bug file header
141+
5. Commit and push changes
142+
143+
### Example 2: Bug Status Update
144+
1. Fix bug in code
145+
2. Update local bug file status to "Fixed"
146+
3. Run: `gh issue close 42 --comment "Fixed in commit abc123"`
147+
4. Commit local file changes
148+
149+
### Example 3: Community Report
150+
1. Community reports bug via GitHub Issue #45
151+
2. Create `docs/bugs/BUG-2025-01-003-community-report.md`
152+
3. Add GitHub Issue #45 reference to header
153+
4. Update README.md bug list
154+
5. Commit changes
155+
156+
## Benefits
157+
158+
- **Dual Tracking**: Detailed technical docs + community visibility
159+
- **Version Control**: Bug documentation versioned with code
160+
- **Searchability**: Local grep + GitHub search
161+
- **Integration**: Links between documentation and issue tracking
162+
- **Automation**: Potential for automated synchronization
163+
- **Collaboration**: Community can reference detailed technical info

0 commit comments

Comments
 (0)