Skip to content

Commit 3fb7c2f

Browse files
Copilotmoshesham
Copilot
and
moshesham
committed
Add comprehensive documentation for creating cleanup issues
Co-authored-by: moshesham <[email protected]>
1 parent 182fe46 commit 3fb7c2f

File tree

2 files changed

+324
-0
lines changed

2 files changed

+324
-0
lines changed

‎CLEANUP_SUMMARY.md‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
# Codebase Cleanup - Issues Summary
2+
3+
## Overview
4+
5+
This directory contains documentation for a comprehensive cleanup of the Product Analytics MasterClass repository. Seven detailed GitHub issues have been prepared to systematically address organizational and structural problems in the codebase.
6+
7+
## Files in This Package
8+
9+
1. **ISSUES_TO_CREATE.md** (Main document - ~500 lines)
10+
- Contains 7 fully detailed GitHub issues
11+
- Each issue includes problem description, analysis, solutions, and definition of done
12+
- Ready to be copied to GitHub Issues one at a time
13+
14+
2. **HOW_TO_CREATE_ISSUES.md** (Instructions)
15+
- Step-by-step guide for creating issues on GitHub
16+
- Includes manual method, CLI method, and automated script
17+
- Provides checklist and best practices
18+
19+
3. **.github/ISSUE_TEMPLATE.md** (Template)
20+
- Reusable template for future cleanup issues
21+
- Ensures consistency in issue creation
22+
23+
## The 7 Issues
24+
25+
### Issue #1: Consolidate duplicate build_book.sh scripts
26+
- **Priority:** High
27+
- **Effort:** Small (1-2 hours)
28+
- **Labels:** `cleanup`, `documentation`, `scripts`
29+
- **Summary:** Remove duplicate build scripts and standardize on one
30+
31+
### Issue #2: Evaluate Content folder usage and redundancy
32+
- **Priority:** Medium
33+
- **Effort:** Medium (3-4 hours)
34+
- **Labels:** `cleanup`, `documentation`, `content-structure`
35+
- **Summary:** Determine purpose of Content/ folder and eliminate redundancy
36+
37+
### Issue #3: Restore or remove week directory structure in book-src
38+
- **Priority:** High
39+
- **Effort:** Small-Medium (2-3 hours)
40+
- **Labels:** `cleanup`, `structure`, `decision-needed`
41+
- **Summary:** Decide whether to restore week-based organization or keep flat structure
42+
43+
### Issue #4: Populate or remove empty placeholder report files
44+
- **Priority:** Medium
45+
- **Effort:** Large (8-12 hours if creating content)
46+
- **Labels:** `cleanup`, `content`, `reports`
47+
- **Summary:** Fill in or remove 9 empty/placeholder report files
48+
49+
### Issue #5: Review and update documentation files for consistency
50+
- **Priority:** Medium
51+
- **Effort:** Medium (3-4 hours)
52+
- **Labels:** `documentation`, `cleanup`, `consistency`
53+
- **Summary:** Update README, CONTRIBUTING, and other docs to reflect current structure
54+
55+
### Issue #6: Improve SUMMARY.md generation and book navigation
56+
- **Priority:** High
57+
- **Effort:** Small-Medium (2-3 hours)
58+
- **Labels:** `enhancement`, `user-experience`, `mdbook`
59+
- **Summary:** Enhance mdBook table of contents for better navigation
60+
61+
### Issue #7: Comprehensive codebase audit and cleanup roadmap
62+
- **Priority:** High
63+
- **Effort:** Medium (4-6 hours for audit)
64+
- **Labels:** `epic`, `cleanup`, `planning`
65+
- **Summary:** Meta-issue to track overall cleanup progress and identify additional items
66+
67+
## Recommended Creation Order
68+
69+
1. **Issue #1** - Quick win that unblocks other work
70+
2. **Issue #2** - Strategic decision about content organization
71+
3. **Issue #3** - Depends on Issue #2 decision
72+
4. **Issue #4** - Can be done in parallel with others
73+
5. **Issue #5** - Should be done after #1-3 are resolved
74+
6. **Issue #6** - Depends on decisions from #2 and #3
75+
7. **Issue #7** - Meta-issue to track everything
76+
77+
## Quick Start
78+
79+
### Option 1: Manual Creation (5-10 minutes per issue)
80+
1. Open `ISSUES_TO_CREATE.md`
81+
2. Copy each issue section
82+
3. Create new GitHub issue
83+
4. Paste content and add labels
84+
5. Repeat for all 7 issues
85+
86+
### Option 2: Automated Creation (5 minutes total)
87+
1. Read `HOW_TO_CREATE_ISSUES.md`
88+
2. Use the provided bash script
89+
3. Run: `./create_issues.sh`
90+
4. All 7 issues created automatically
91+
92+
## What's Included in Each Issue
93+
94+
Every issue contains:
95+
96+
- ✅ **Problem Description** - Clear explanation of what needs fixing
97+
- ✅ **Current State Analysis** - Detailed assessment with file references
98+
- ✅ **Impact** - Why this matters and what problems it causes
99+
- ✅ **Recommended Solutions** - Multiple options with pros/cons
100+
- ✅ **Files to Check/Update** - Specific file checklist
101+
- ✅ **Definition of Done** - Clear completion criteria
102+
- ✅ **Related Issues** - Cross-references to other issues
103+
- ✅ **Additional Context** - Background information and rationale
104+
105+
## Total Effort Estimate
106+
107+
- **Audit & Planning:** 6-10 hours (Issues #7, #2, #3)
108+
- **Quick Wins:** 3-5 hours (Issues #1, #6)
109+
- **Documentation:** 3-4 hours (Issue #5)
110+
- **Content Creation:** 8-12 hours (Issue #4, if creating content)
111+
112+
**Total:** 20-31 hours depending on decisions made
113+
114+
## Dependencies Between Issues
115+
116+
```
117+
Issue #1 (Build scripts)
118+
└─> Issue #5 (Documentation) - docs reference build scripts
119+
120+
Issue #2 (Content folder)
121+
└─> Issue #3 (Week directories) - structure decision
122+
└─> Issue #6 (SUMMARY.md) - navigation depends on structure
123+
124+
Issue #3 (Week directories)
125+
└─> Issue #6 (SUMMARY.md) - navigation depends on structure
126+
127+
Issue #4 (Reports)
128+
└─> Issue #6 (SUMMARY.md) - what to list in TOC
129+
130+
Issue #7 (Audit)
131+
└─> All issues - tracks overall progress
132+
```
133+
134+
## Success Criteria
135+
136+
This cleanup effort will be successful when:
137+
138+
1. ✅ No duplicate or conflicting files exist
139+
2. ✅ All documentation is current and accurate
140+
3. ✅ Build process is streamlined and well-documented
141+
4. ✅ Content organization is clear and logical
142+
5. ✅ All files have a clear purpose and are referenced
143+
6. ✅ Navigation experience is smooth for learners
144+
7. ✅ Repository is easy to maintain going forward
145+
146+
## Getting Help
147+
148+
- Read the full issue descriptions in `ISSUES_TO_CREATE.md`
149+
- Follow the creation guide in `HOW_TO_CREATE_ISSUES.md`
150+
- Use `.github/ISSUE_TEMPLATE.md` for any new cleanup issues
151+
- Reference this summary for overview and priorities
152+
153+
## Next Steps
154+
155+
1. Review `ISSUES_TO_CREATE.md` to understand all issues
156+
2. Follow `HOW_TO_CREATE_ISSUES.md` to create issues on GitHub
157+
3. Prioritize and assign issues to team members
158+
4. Begin work on Issue #1 (quick win)
159+
5. Make strategic decisions on Issues #2 and #3
160+
6. Track progress using Issue #7 as epic
161+
162+
---
163+
164+
**Created:** 2025-11-13
165+
**Repository:** Analytical-Guide/Product-Analytics-MasterClass
166+
**Purpose:** Comprehensive codebase cleanup and organization
167+

‎HOW_TO_CREATE_ISSUES.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
# How to Create GitHub Issues from ISSUES_TO_CREATE.md
2+
3+
This guide explains how to create the cleanup issues one at a time on GitHub.
4+
5+
## Prerequisites
6+
7+
- GitHub account with write access to the repository
8+
- Familiarity with GitHub Issues interface
9+
10+
## Method 1: Using GitHub Web UI (Recommended)
11+
12+
For each issue in `ISSUES_TO_CREATE.md`:
13+
14+
1. **Navigate to Issues**
15+
- Go to https://github.com/Analytical-Guide/Product-Analytics-MasterClass/issues
16+
- Click "New Issue" button
17+
18+
2. **Copy Issue Content**
19+
- Open `ISSUES_TO_CREATE.md` in the repository
20+
- Find the issue section (e.g., "## Issue #1: ...")
21+
- Copy everything from the title to the end of that issue's content
22+
- Stop before the next "## Issue #X" heading
23+
24+
3. **Create the Issue**
25+
- Paste the copied content into the issue description
26+
- Extract the title from the first line (e.g., "Consolidate duplicate build_book.sh scripts")
27+
- Add appropriate labels as specified in the issue
28+
- Submit the issue
29+
30+
4. **Repeat for Each Issue**
31+
- Follow the recommended order:
32+
1. Issue #1 (Build scripts)
33+
2. Issue #2 (Content folder)
34+
3. Issue #3 (Week directories)
35+
4. Issue #4 (Report files)
36+
5. Issue #5 (Documentation)
37+
6. Issue #6 (SUMMARY.md)
38+
7. Issue #7 (Audit roadmap)
39+
40+
## Method 2: Using GitHub CLI
41+
42+
If you have `gh` CLI installed and authenticated:
43+
44+
```bash
45+
# Navigate to repository
46+
cd /path/to/Product-Analytics-MasterClass
47+
48+
# Create Issue #1
49+
gh issue create \
50+
--title "Consolidate duplicate build_book.sh scripts" \
51+
--label "cleanup,documentation,scripts" \
52+
--body-file <(sed -n '/^## Issue #1/,/^## Issue #2/p' ISSUES_TO_CREATE.md | head -n -1)
53+
54+
# Create Issue #2
55+
gh issue create \
56+
--title "Evaluate Content folder usage and redundancy" \
57+
--label "cleanup,documentation,content-structure" \
58+
--body-file <(sed -n '/^## Issue #2/,/^## Issue #3/p' ISSUES_TO_CREATE.md | head -n -1)
59+
60+
# ... repeat for issues #3-7
61+
```
62+
63+
## Method 3: Automated Script
64+
65+
A bash script to create all issues at once:
66+
67+
```bash
68+
#!/bin/bash
69+
70+
# Array of issue titles
71+
titles=(
72+
"Consolidate duplicate build_book.sh scripts"
73+
"Evaluate Content folder usage and redundancy"
74+
"Restore or remove week directory structure in book-src"
75+
"Populate or remove empty placeholder report files"
76+
"Review and update documentation files for consistency"
77+
"Improve SUMMARY.md generation and book navigation"
78+
"Comprehensive codebase audit and cleanup roadmap"
79+
)
80+
81+
# Array of labels
82+
labels=(
83+
"cleanup,documentation,scripts"
84+
"cleanup,documentation,content-structure"
85+
"cleanup,structure,decision-needed"
86+
"cleanup,content,reports"
87+
"documentation,cleanup,consistency"
88+
"enhancement,user-experience,mdbook"
89+
"epic,cleanup,planning"
90+
)
91+
92+
# Create each issue
93+
for i in {1..7}; do
94+
echo "Creating Issue #$i: ${titles[$i-1]}"
95+
96+
# Extract issue content from ISSUES_TO_CREATE.md
97+
if [ $i -eq 7 ]; then
98+
# Last issue goes to end of file
99+
body=$(sed -n "/^## Issue #$i:/,\$p" ISSUES_TO_CREATE.md)
100+
else
101+
# Other issues go until next issue
102+
next=$((i + 1))
103+
body=$(sed -n "/^## Issue #$i:/,/^## Issue #$next:/p" ISSUES_TO_CREATE.md | head -n -1)
104+
fi
105+
106+
# Create the issue
107+
echo "$body" | gh issue create \
108+
--title "${titles[$i-1]}" \
109+
--label "${labels[$i-1]}" \
110+
--body-file -
111+
112+
echo "✓ Issue #$i created"
113+
echo ""
114+
115+
# Brief pause to avoid rate limiting
116+
sleep 2
117+
done
118+
119+
echo "All issues created successfully!"
120+
```
121+
122+
Save this as `create_issues.sh`, make it executable with `chmod +x create_issues.sh`, and run it.
123+
124+
## Issue Creation Checklist
125+
126+
For each issue you create, verify:
127+
128+
- [ ] Title matches the issue heading
129+
- [ ] All content from that issue section is included
130+
- [ ] Labels are added as specified
131+
- [ ] The issue number is visible in the created issue
132+
- [ ] Related issues are cross-referenced (you may need to edit and add links after all issues are created)
133+
134+
## After Creating All Issues
135+
136+
1. **Update Cross-References**
137+
- Go back through each issue
138+
- Update "Related Issues" sections with actual issue numbers
139+
- Add links to related issues
140+
141+
2. **Create Project Board (Optional)**
142+
- Create a GitHub Project for "Codebase Cleanup"
143+
- Add all 7 issues to the project
144+
- Organize by priority/status
145+
146+
3. **Assign and Prioritize**
147+
- Assign issues to team members
148+
- Set milestones if appropriate
149+
- Add to project boards
150+
151+
## Notes
152+
153+
- The issues are designed to be created in order, as later issues reference earlier ones
154+
- Each issue is self-contained with full context
155+
- Issues #1-3 should be prioritized as they unblock other work
156+
- Issue #7 serves as an epic to track overall progress
157+

0 commit comments

Comments
 (0)