WHOOSH/docs/decisions/2025-09-21-standardized-label-ecosystem.md

DR: Standardized Label Ecosystem for CHORUS Repositories

Date: 2025-09-21 Status: Accepted UCXL: ucxl://ops:planner@WHOOSH:label-management/DRs/2025-09-21-standardized-label-ecosystem.md

Problem

WHOOSH automatically creates labels when repositories are added to the monitoring system, but the current label set differs from the standardized conventions used across the CHORUS ecosystem (WHOOSH, CHORUS, KACHING repositories). This creates inconsistency in issue management and developer experience across the ecosystem.

Current State Analysis

WHOOSH Auto-Created Labels (Prior Implementation):

• bzzz-task (#ff6b6b) - Issues for CHORUS task conversion
• whoosh-monitored (#4ecdc4) - Repository monitoring indicator
• priority-high (#e74c3c) - High priority tasks
• priority-medium (#f39c12) - Medium priority tasks
• priority-low (#95a5a6) - Low priority tasks

Ecosystem Standard Labels (WHOOSH Repository):

• bug (#ee0701) - Something is not working
• bzzz-task (#5319e7) - CHORUS task for auto ingestion
• duplicate (#cccccc) - This issue or pull request already exists
• enhancement (#84b6eb) - New feature
• help wanted (#128a0c) - Need some help
• invalid (#e6e6e6) - Something is wrong
• question (#cc317c) - More information is needed
• wontfix (#ffffff) - This won't be fixed

Options Considered

Option 1: Maintain Current Custom Labels

Pros:

• No changes required to existing code
• Maintains WHOOSH-specific functionality (priority labels)
• No risk of breaking existing repositories

Cons:

• Inconsistent with ecosystem standards
• Poor developer experience (unfamiliar labels)
• Limits tool integration with GitHub-standard workflows
• Creates confusion when moving between repositories

Option 2: Adopt GitHub Standard Labels Only

Pros:

• Maximum compatibility with external tools
• Familiar to all developers
• Industry standard approach

Cons:

• Loses WHOOSH-specific functionality (priority classification)
• May not adequately support CHORUS workflow automation
• No bzzz-task integration for automated task creation

Option 3: Hybrid Approach - Ecosystem Standards + Optional Extensions (Chosen)

Pros:

• Consistent with ecosystem-wide conventions
• Maintains GitHub-standard familiarity
• Preserves bzzz-task automation integration
• Allows future addition of priority labels as enhancement
• Provides clear migration path

Cons:

• Requires updating existing implementation
• Existing repositories may have inconsistent labels until sync

Decision

Adopt the standardized CHORUS ecosystem label set as the default for all repositories added to WHOOSH monitoring. This includes all 8 labels currently used in the WHOOSH repository itself.

Implementation Details

Updated Label Set:

requiredLabels := []CreateLabelRequest{
    {Name: "bug", Color: "ee0701", Description: "Something is not working"},
    {Name: "bzzz-task", Color: "5319e7", Description: "CHORUS task for auto ingestion."},
    {Name: "duplicate", Color: "cccccc", Description: "This issue or pull request already exists"},
    {Name: "enhancement", Color: "84b6eb", Description: "New feature"},
    {Name: "help wanted", Color: "128a0c", Description: "Need some help"},
    {Name: "invalid", Color: "e6e6e6", Description: "Something is wrong"},
    {Name: "question", Color: "cc317c", Description: "More information is needed"},
    {Name: "wontfix", Color: "ffffff", Description: "This won't be fixed"},
}

Key Changes:

1. Color Correction: bzzz-task color updated from #ff6b6b to #5319e7
2. Standard Labels Added: All GitHub-standard issue management labels
3. Custom Labels Removed: whoosh-monitored, priority labels (can be re-added as enhancement)
4. Ecosystem Alignment: Matches WHOOSH, CHORUS, KACHING repository standards

Affected Components

Automatic Integration:

• internal/gitea/client.go:EnsureRequiredLabels() - Core label creation logic
• internal/server/server.go:createRepositoryHandler - Automatic execution on repo addition
• internal/server/server.go:ensureRepositoryLabelsHandler - Manual sync endpoint

Requirement Traceability:

• All modified functions include @goal: WHOOSH-LABELS-004 tags
• Inline comments explain rationale and ecosystem alignment
• Full traceability from issue #4 through implementation

Impact Assessment

Positive Impacts

1. Ecosystem Consistency: All CHORUS repositories have identical label conventions
2. Developer Experience: Familiar GitHub-standard labels reduce cognitive overhead
3. Tool Integration: Better compatibility with external issue management tools
4. Maintenance: Simplified label management across multiple repositories
5. Automation: Preserved bzzz-task integration for CHORUS workflow automation

Risk Mitigation

1. Backward Compatibility: Existing repositories continue to function with old labels
2. Graceful Degradation: Label creation failures don't block repository monitoring
3. Manual Sync: API endpoint available for updating existing repositories
4. Rollback Plan: Can revert to previous label set if critical issues arise

Migration Strategy

1. New Repositories: Automatically receive standardized labels
2. Existing Repositories: Manual sync via API endpoint as needed
3. Monitoring: No impact on issue detection or monitoring functionality
4. Documentation: Update guides to reflect new label conventions

Future Enhancements

Planned Extensions

1. Priority Labels: Add as optional/configurable feature
2. Repository-Specific Labels: Support for custom labels per repository type
3. Label Validation: Automated checking to ensure labels remain consistent
4. Migration Tools: Bulk update tools for existing repository sets

Configuration Options

Future consideration for making label sets configurable:

label_sets:
  standard: [bug, enhancement, question, ...]
  priority: [priority-high, priority-medium, priority-low]
  monitoring: [whoosh-monitored, status-active, ...]

Evidence and References

• Issue: WHOOSH #4 - Standardize Automatic Label Creation to Match Ecosystem Convention
• Implementation: internal/gitea/client.go, internal/server/server.go
• Manual Verification: Successfully tested label creation on CHORUS and KACHING repositories
• Ecosystem Audit: Confirmed WHOOSH, CHORUS, KACHING all use identical label sets post-implementation

Acceptance Criteria Validation

✅ EnsureRequiredLabels() creates all 8 standardized labels ✅ bzzz-task label uses correct color (#5319e7) ✅ All labels match WHOOSH repository standards exactly ✅ Automatic creation works on repository addition ✅ Manual sync endpoint functions correctly ✅ No breaking changes to existing monitoring functionality ✅ Inline comments include @goal: traceability tags ✅ Decision record documents rationale and implementation

Conclusion

This change aligns WHOOSH with ecosystem-wide conventions while preserving essential automation functionality. The standardized approach improves developer experience and tool compatibility while maintaining the flexibility to add domain-specific labels as future enhancements.

The implementation maintains backward compatibility and provides clear migration paths, ensuring a smooth transition to the new standardized approach.