|
6 | 6 | {"id":"bluefin-docs-bdg","title":"Investigate .planning directory structure","description":"Check if .planning directory exists and analyze its structure to understand the current work tracking system that needs to be migrated to beads. Need to understand:\n- Directory structure and file organization\n- Issue/task format and metadata\n- Dependency tracking approach\n- Current status of work items\n- Migration strategy to beads","status":"closed","priority":1,"issue_type":"task","owner":"jorge.castro@gmail.com","created_at":"2026-01-31T00:34:48.473828624-05:00","created_by":"Jorge O. Castro","updated_at":"2026-01-31T00:37:59.53986077-05:00","closed_at":"2026-01-31T00:37:59.53986077-05:00","close_reason":"Investigation complete. Found .planning structure with todos, phases, and documentation. All pending todos migrated to beads."} |
7 | 7 | {"id":"bluefin-docs-e33","title":"Add Community Engagement section to monthly reports","description":"## Problem\n\nMonthly reports currently show contributors by PR authorship only (merged PRs). This misses valuable community engagement from:\n- Discussion participants (comments, reactions, helpful answers)\n- Issue reporters and triagers\n- Code reviewers\n- Community support providers\n\nWe want a \"Community Engagement\" section alongside the existing contributors section that highlights top community participants based on broader engagement metrics.\n\n## Key Research Questions\n\n1. **What metrics to track?**\n - Discussion comments/replies\n - Issue comments (excluding PR comments)\n - Reactions given/received\n - Helpful answer marks in discussions\n - Code review comments\n\n2. **Top 10 or Top 20?**\n - Depends on activity volume in monitored repos\n - Need to query live data to determine typical engagement levels\n - Should avoid showing mostly zeros\n\n3. **New Light subsection?**\n - Similar to \"🌟 New Contributors\" for first-time PR authors\n - Could show \"🌟 New Voices\" for first-time discussion/issue participants\n - Would require historical tracking similar to contributors-history.json\n\n4. **Data sources:**\n - GitHub Discussions API (projectbluefin/common, ublue-os/bluefin)\n - GitHub Issues API (all monitored repos)\n - GitHub Pull Request Review API (all monitored repos)\n\n## Solution\n\n**Phase 1: Research \u0026 Design**\n\n1. Query live GitHub API data for December 2024 and January 2025 (existing report months)\n2. Analyze engagement patterns:\n - How many unique discussion participants per month?\n - How many unique issue commenters (non-PR)?\n - What's the distribution? (Are there 5 active people or 50?)\n3. Determine appropriate threshold:\n - If 5-15 active: Top 10\n - If 15-30 active: Top 20\n - If \u003c5 active: May not be worth separate section\n\n**Phase 2: Implementation**\n\n1. Add GraphQL queries for:\n - Discussion comments in date range\n - Issue comments (non-PR) in date range\n - PR review comments in date range\n2. Build engagement scoring system:\n - Weight different activity types (discussion reply \u003e reaction)\n - Filter out bot accounts\n - Aggregate by author\n3. Add \"Community Engagement\" section to markdown generator:\n - Top N most engaged community members\n - Show engagement type breakdown (discussions, issues, reviews)\n - Optional \"New Voices\" subsection for first-timers\n4. Update historical tracking:\n - Either extend contributors-history.json to include engagement\n - Or create separate engagement-history.json\n - Ensure query-based detection like contributor system\n\n**Phase 3: Validation**\n\n1. Generate test reports with engagement data\n2. Verify bot filtering works correctly\n3. Confirm \"New Voices\" detection is accurate\n4. Check that section adds value (not mostly empty)\n\n## Files Modified\n- scripts/generate-report.mjs\n- scripts/lib/graphql-queries.mjs\n- scripts/lib/markdown-generator.mjs\n- reports/\n\n## Research Starting Points\n- GitHub GraphQL API Explorer: https://docs.github.com/en/graphql/overview/explorer\n- Discussion queries: `repository.discussions` with `comments` connection\n- Issue queries: `repository.issues` with `comments` connection (filter `isPullRequest: false`)\n- Review queries: `repository.pullRequests` with `reviews` connection\n\n## Success Criteria\n- [ ] Live data analysis complete (sample size, distribution)\n- [ ] Top N threshold determined (10 vs 20)\n- [ ] GraphQL queries return engagement metrics\n- [ ] Engagement scoring system designed\n- [ ] Bot filtering verified\n- [ ] Historical tracking approach decided\n- [ ] \"New Voices\" detection implemented (if feasible)\n- [ ] Test reports show valuable engagement data\n\n---\n*Migrated from .planning/todos/pending/2026-01-29-add-community-engagement-section.md (created: 2026-01-29)*","status":"open","priority":2,"issue_type":"feature","owner":"jorge.castro@gmail.com","created_at":"2026-01-31T00:36:49.293306937-05:00","created_by":"Jorge O. Castro","updated_at":"2026-01-31T00:36:49.293306937-05:00","labels":["community","enhancement","reports"]} |
8 | 8 | {"id":"bluefin-docs-itu","title":"Add homebrew tap promotion section to monthly reports","description":"## Problem\n\nMonthly reports should include a section showing packages that have been promoted from the experimental-tap to the production-tap during the reporting period. This helps users discover newly production-ready packages.\n\nThe section should:\n- Appear in monthly reports (not in command-line documentation)\n- List packages promoted during the month with descriptions\n- Include a link to http://github.com/ublue-os/homebrew-tap\n- Use specific wording: \"Use `ujust bbrew` to browse and install these packages. Follow [the tap instructions] if you want to do it by hand.\"\n\n## Solution\n\n**Research Promotions Workflow:**\n1. Identify how packages move from experimental-tap to homebrew-tap\n2. Determine what commit messages/patterns indicate a promotion\n3. Example: commit `bd381cf` (Jan 12, 2026) promoted antigravity-linux\n\n**Add Data Fetching to Report Generator:**\n1. Query both experimental-tap and homebrew-tap repositories\n2. Compare commits between taps to detect promotions\n3. Filter commits by date range (report month)\n4. Extract package names and descriptions from formulas/casks\n\n**Add Markdown Generation:**\n1. Create new section in `scripts/lib/markdown-generator.mjs`\n2. Format: \"## Homebrew Tap Promotions\" section\n3. List promoted packages with bullet points\n4. Include package descriptions from formula/cask files\n5. Add footer with usage instructions and tap link\n\n**Integration:**\n1. Wire up in `scripts/generate-report.mjs`\n2. Position section after \"Contributors\" but before footer\n3. Handle case where no promotions occurred (skip section or show \"None this month\")\n\n## Implementation Notes\n\n**Promotion Detection Strategy:**\n\nOption 1: GitHub API commits comparison\n- Fetch commits from both repos in date range\n- Look for new files added to homebrew-tap/Formula or homebrew-tap/Casks\n- Cross-reference with experimental-tap to confirm they existed there first\n\nOption 2: Commit message parsing\n- Look for specific commit patterns like \"feat: promote X to main tap\"\n- Simpler but less reliable if commit messages aren't consistent\n\n**Package Description Extraction:**\n- Parse Ruby formula files to extract `desc` field\n- Example: `desc \"Antigravity application for Linux\"`\n- Cache descriptions to avoid repeated parsing\n\n**Known Promotions (for testing):**\n- antigravity-linux (Jan 12, 2026 - commit bd381cf)\n- goose-linux (frequent updates, check if promotion or just updates)\n- linux-mcp-server (Jan 26, 2026 - commit 90a8c88)\n\n## Files Modified\n- scripts/generate-report.mjs\n- scripts/lib/markdown-generator.mjs\n- reports/\n\n## Success Criteria\n- [ ] Report generator detects promotions from experimental to production tap\n- [ ] Promotions section appears in monthly reports when promotions occurred\n- [ ] Package descriptions accurately extracted from formula files\n- [ ] Section omitted or shows \"None this month\" when no promotions\n- [ ] Usage instructions and tap link included\n- [ ] Test with January 2026 report (known promotions: antigravity, linux-mcp-server)\n\n---\n*Migrated from .planning/todos/pending/2026-01-29-add-homebrew-tap-promotion-section.md (created: 2026-01-29)*","status":"open","priority":2,"issue_type":"feature","owner":"jorge.castro@gmail.com","created_at":"2026-01-31T00:37:06.083488312-05:00","created_by":"Jorge O. Castro","updated_at":"2026-01-31T00:37:06.083488312-05:00","labels":["enhancement","homebrew","reports"]} |
9 | | -{"id":"bluefin-docs-k89","title":"Upgrade Node.js from 18 to latest LTS version","description":"## Problem\n\nNode.js 18 has reached End of Life (EOL) as of April 2025. The project currently specifies:\n- `package.json` engines: `\"node\": \"\u003e=18.0\"`\n- Monthly reports workflow: `node-version: \"18\"`\n- Other workflows mix Node 20 and \"latest\"\n\nContinuing to use EOL Node versions creates security and compatibility risks:\n- No security patches for vulnerabilities\n- Incompatibility with newer dependencies\n- CI/CD failures as actions drop Node 18 support\n- Package managers may deprecate Node 18 in their own tooling\n\nThe inconsistency across workflows (18 in monthly-reports, 20 in pages/driver-versions, latest in renovate) suggests the upgrade was partially done but not completed.\n\n## Solution\n\n**Recommended:** Upgrade to Node.js 22 LTS (Active LTS as of October 2024, supported until April 2027)\n\n**Upgrade Plan:**\n\n1. **Update Configuration Files:**\n - `package.json`: Change engines to `\"node\": \"\u003e=22.0\"`\n - `.github/workflows/monthly-reports.yml`: Change to `node-version: \"22\"`\n - Standardize all workflows to use Node 22\n\n2. **Test Locally:**\n - Switch to Node 22: `nvm use 22` or equivalent\n - Clear node_modules: `rm -rf node_modules package-lock.json`\n - Reinstall: `npm install --legacy-peer-deps`\n - Run validation suite:\n - `npm run typecheck`\n - `npm run prettier-lint`\n - `npm run build`\n - `npm run generate-report -- --month=2026-01`\n - Test dev server: `npm start`\n\n3. **Verify All Workflows:**\n - Trigger each workflow manually via GitHub Actions\n - Verify monthly reports generation still works\n - Check driver versions update workflow\n - Validate pages deployment\n\n4. **Update Documentation:**\n - `AGENTS.md`: Update Node version references (currently mentions 18.x)\n - `.planning/STATE.md`: Update technical notes section\n - Update any installation docs\n\n5. **Commit Strategy:**\n - Single atomic commit with all version bumps\n - Test in CI before merging\n - Monitor first production build after merge\n\n**Risk Assessment:**\n- Low risk: Node 22 is LTS and Docusaurus 3.8.1 supports it\n- Potential issues: Dependency peer warnings (already using --legacy-peer-deps)\n- Mitigation: Full test suite before commit\n\n**Alternative:** Node 20 LTS (Maintenance mode, supported until April 2026)\n- Safer short-term option if Node 22 causes issues\n- Would require another upgrade in ~12 months\n\n## Files Modified\n- package.json:9-10\n- .github/workflows/monthly-reports.yml:31\n- .github/workflows/pages.yml\n- .github/workflows/update-driver-versions.yml\n\n## References\n- Node.js release schedule: https://nodejs.org/en/about/previous-releases\n- Docusaurus system requirements: https://docusaurus.io/docs/installation#requirements\n\n---\n*Migrated from .planning/todos/pending/2026-01-28-upgrade-node-18-to-latest-lts.md (created: 2026-01-28)*","status":"open","priority":1,"issue_type":"task","owner":"jorge.castro@gmail.com","created_at":"2026-01-31T00:36:30.816680601-05:00","created_by":"Jorge O. Castro","updated_at":"2026-01-31T00:36:30.816680601-05:00","labels":["dependencies","security","tooling"]} |
| 9 | +{"id":"bluefin-docs-k89","title":"Upgrade Node.js from 18 to latest LTS version","description":"## Problem\n\nNode.js 18 has reached End of Life (EOL) as of April 2025. The project currently specifies:\n- `package.json` engines: `\"node\": \"\u003e=18.0\"`\n- Monthly reports workflow: `node-version: \"18\"`\n- Other workflows mix Node 20 and \"latest\"\n\nContinuing to use EOL Node versions creates security and compatibility risks:\n- No security patches for vulnerabilities\n- Incompatibility with newer dependencies\n- CI/CD failures as actions drop Node 18 support\n- Package managers may deprecate Node 18 in their own tooling\n\nThe inconsistency across workflows (18 in monthly-reports, 20 in pages/driver-versions, latest in renovate) suggests the upgrade was partially done but not completed.\n\n## Solution\n\n**Recommended:** Upgrade to Node.js 22 LTS (Active LTS as of October 2024, supported until April 2027)\n\n**Upgrade Plan:**\n\n1. **Update Configuration Files:**\n - `package.json`: Change engines to `\"node\": \"\u003e=22.0\"`\n - `.github/workflows/monthly-reports.yml`: Change to `node-version: \"22\"`\n - Standardize all workflows to use Node 22\n\n2. **Test Locally:**\n - Switch to Node 22: `nvm use 22` or equivalent\n - Clear node_modules: `rm -rf node_modules package-lock.json`\n - Reinstall: `npm install --legacy-peer-deps`\n - Run validation suite:\n - `npm run typecheck`\n - `npm run prettier-lint`\n - `npm run build`\n - `npm run generate-report -- --month=2026-01`\n - Test dev server: `npm start`\n\n3. **Verify All Workflows:**\n - Trigger each workflow manually via GitHub Actions\n - Verify monthly reports generation still works\n - Check driver versions update workflow\n - Validate pages deployment\n\n4. **Update Documentation:**\n - `AGENTS.md`: Update Node version references (currently mentions 18.x)\n - `.planning/STATE.md`: Update technical notes section\n - Update any installation docs\n\n5. **Commit Strategy:**\n - Single atomic commit with all version bumps\n - Test in CI before merging\n - Monitor first production build after merge\n\n**Risk Assessment:**\n- Low risk: Node 22 is LTS and Docusaurus 3.8.1 supports it\n- Potential issues: Dependency peer warnings (already using --legacy-peer-deps)\n- Mitigation: Full test suite before commit\n\n**Alternative:** Node 20 LTS (Maintenance mode, supported until April 2026)\n- Safer short-term option if Node 22 causes issues\n- Would require another upgrade in ~12 months\n\n## Files Modified\n- package.json:9-10\n- .github/workflows/monthly-reports.yml:31\n- .github/workflows/pages.yml\n- .github/workflows/update-driver-versions.yml\n\n## References\n- Node.js release schedule: https://nodejs.org/en/about/previous-releases\n- Docusaurus system requirements: https://docusaurus.io/docs/installation#requirements\n\n---\n*Migrated from .planning/todos/pending/2026-01-28-upgrade-node-18-to-latest-lts.md (created: 2026-01-28)*","notes":"PARTIAL COMPLETION FOUND:\n- ✅ All GitHub Actions workflows upgraded to Node 20\n - pages.yml: node-version: 20\n - monthly-reports.yml: node-version: \"20\"\n - update-driver-versions.yml: node-version: \"20\"\n- ❌ package.json engines field still shows: \"node\": \"\u003e=18.0\"\n\nREMAINING WORK:\n- Update package.json engines to require Node 20+\n- Update any documentation mentioning Node 18\n- Test local builds with Node 20\n- Update AGENTS.md if it references Node version","status":"closed","priority":1,"issue_type":"task","owner":"jorge.castro@gmail.com","created_at":"2026-01-31T00:36:30.816680601-05:00","created_by":"Jorge O. Castro","updated_at":"2026-02-01T18:20:47.888066107-05:00","closed_at":"2026-02-01T18:20:47.888066107-05:00","close_reason":"Completed: Updated Node.js requirement to 20+ in package.json, AGENTS.md, README.md, and docs/devcontainers.md. Package-lock.json regenerated. Pull request #613 created for review: https://github.com/projectbluefin/documentation/pull/613","labels":["dependencies","security","tooling"]} |
10 | 10 | {"id":"bluefin-docs-lm9","title":"Clean up and archive .planning after migration","description":"After migration is complete:\n- Verify all work items are in beads\n- Archive .planning directory (move to .planning.archived or similar)\n- Update PROJECT-HINTS.md to reference beads instead of .planning\n- Update any documentation that references .planning\n- Commit changes to repository","status":"closed","priority":1,"issue_type":"task","owner":"jorge.castro@gmail.com","created_at":"2026-01-31T00:35:05.429434249-05:00","created_by":"Jorge O. Castro","updated_at":"2026-01-31T00:42:21.163664746-05:00","closed_at":"2026-01-31T00:42:21.163664746-05:00","close_reason":"Migration from .planning to beads complete: created MIGRATION.md documentation, renamed .planning to .planning-archive, and updated AGENTS.md with beads usage guide","dependencies":[{"issue_id":"bluefin-docs-lm9","depends_on_id":"bluefin-docs-9hl","type":"blocks","created_at":"2026-01-31T00:35:05.4306469-05:00","created_by":"Jorge O. Castro"}]} |
11 | 11 | {"id":"bluefin-docs-rfy","title":"Test beads setup","description":"Initial test issue to verify beads is working correctly in bluefin-docs repository","status":"closed","priority":2,"issue_type":"task","owner":"jorge.castro@gmail.com","created_at":"2026-01-31T00:32:43.975362391-05:00","created_by":"Jorge O. Castro","updated_at":"2026-01-31T00:33:08.972649459-05:00","closed_at":"2026-01-31T00:33:08.972649459-05:00","close_reason":"Beads setup verified - system working correctly"} |
12 | 12 | {"id":"bluefin-docs-sr2","title":"Analyze .planning directory files and content","description":"Once .planning directory is located, read and analyze the markdown files to understand:\n- File naming conventions\n- Content structure (frontmatter, body format)\n- How tasks/issues are represented\n- How dependencies are tracked\n- Status and priority systems\n- Any custom metadata fields","status":"closed","priority":1,"issue_type":"task","owner":"jorge.castro@gmail.com","created_at":"2026-01-31T00:34:56.633580218-05:00","created_by":"Jorge O. Castro","updated_at":"2026-01-31T00:38:03.259678818-05:00","closed_at":"2026-01-31T00:38:03.259678818-05:00","close_reason":"Analysis complete. Todos migrated. No migration script needed - manual migration was appropriate for small number of items.","dependencies":[{"issue_id":"bluefin-docs-sr2","depends_on_id":"bluefin-docs-bdg","type":"blocks","created_at":"2026-01-31T00:34:56.634820589-05:00","created_by":"Jorge O. Castro"}]} |
|
0 commit comments