Feature and its Use Cases
Overview
I propose improving the Repository Explorer's health score experience by allowing users to click on a repository's health score and view detailed information about it.
Currently, an overall score such as 71 provides a quick summary, but users may not understand what contributes to that score or which areas need attention.
The goal is to make the health score more transparent, understandable, and actionable through an interactive details panel.
Proposed UI
When a user clicks on a repository's health score, a side panel opens with three views:
- Breakdown — Understand why the repository has its score.
- Recommendations — Identify potential areas for improvement.
- Raw Metrics — Explore the data behind the score.
1. Breakdown View (Primary Focus)
The Breakdown view is the main focus of this proposal.
Instead of displaying only the overall score, this view would explain the individual factors contributing to the repository's health score.
Proposed Information
- Individual health categories.
- Component scores.
- Contribution or weight, if supported by the scoring system.
- Visual indicators.
- Short explanations of each category.
Example Categories
- Activity Health
- Issue Health
- Pull Request Health
- Contributor Health
- Maintenance
The categories should be based on the actual scoring system used by the project.
UI Reference
The proposed design shows how users can understand the factors contributing to the overall repository health score.
Why This Matters
A user should be able to answer:
Why does this repository have a health score of 71?
The Breakdown view should provide that explanation without requiring users to inspect multiple separate sections.
2. Recommendations View
The Recommendations view would provide actionable suggestions based on the repository's available health metrics.
Example Recommendations
- Review stale issues.
- Address long-running pull requests.
- Improve repository documentation.
- Review maintenance-related gaps.
Recommendations should be based on actual repository data and clearly defined rules.
UI Reference
The proposed design shows how improvement suggestions could be presented in a dedicated view.
3. Raw Metrics View
The Raw Metrics view would show the underlying repository metrics used in the health score calculation.
Example Metrics
Activity
- Commit activity.
- Recent development activity.
Issues
- Open issues.
- Closed issues.
- Stale issues.
Pull Requests
- Open pull requests.
- Merged pull requests.
- Long-running pull requests.
Contributors
- Contributor statistics.
- Active contributors, if available.
Maintenance
- Repository documentation checks.
- License availability, if used by the scoring system.
The final metrics should be based on the data actually used by the existing scoring implementation.
UI Reference
The proposed design shows how users could inspect the data behind the health score.
4. User Interaction Flow
The proposed interaction would work as follows:
- User opens the Repository Explorer.
- User clicks on a repository's health score.
- A health details side panel opens.
- The Breakdown view is displayed by default.
- User can switch between Breakdown, Recommendations, and Raw Metrics.
- User can understand the score and explore its supporting information.
Complete UI Reference
This screenshot demonstrates the proposed health score interaction and details panel.
5. Technical Considerations
This proposal focuses on improving how users explore and understand health score information. It does not propose creating a separate scoring system.
Before implementation, the existing health score calculation and data flow should be investigated.
Proposed Technical Approach
- Reuse the existing health score calculation and repository data.
- Identify whether component-level scores and weights are already available.
- Avoid duplicating scoring logic inside the UI.
- Ensure the displayed Breakdown is consistent with the actual overall score.
- Handle missing metrics, loading states, and errors.
- Add appropriate tests for the new functionality.
If the current scoring implementation only returns an overall score, it may need to expose additional component-level information for the Breakdown view.
The implementation should follow the existing project architecture and design system.
6. Scope and Priority
Primary Focus: Breakdown
The initial focus would be the interactive Breakdown view:
- Clickable repository health score.
- Health details side panel.
- Component-level score information.
- Explanation of factors contributing to the score.
Supporting Views
- Recommendations.
- Raw Metrics.
These supporting views can be implemented based on available data, project requirements, and maintainer feedback.
7. Relationship to Existing Health Scorecard Work
I understand that Issue #222 proposes a Repository Health & Risk Scorecard.
This proposal focuses on the interactive user experience for exploring an individual repository's health score within the Repository Explorer.
The intention is to complement the existing scoring work by providing a clear way for users to understand the score and inspect its supporting information.
The proposed UI and implementation scope can be adjusted to align with the existing health score architecture.
8. Expected Outcome
The proposed feature would help users move from:
Overall Score → Breakdown → Supporting Metrics → Potential Improvements
This would make repository health scores easier to understand and provide users with more context about the factors affecting repository health.
Questions for Maintainers
- Does the existing health score implementation expose the data required for a detailed Breakdown view?
- Can this interaction be integrated into the current Repository Explorer?
- Which component-level scores and metrics are currently available?
- Would this be suitable as a complementary enhancement to the existing health scorecard work?
Additional Context
No response
Code of Conduct
Feature and its Use Cases
Overview
I propose improving the Repository Explorer's health score experience by allowing users to click on a repository's health score and view detailed information about it.
Currently, an overall score such as
71provides a quick summary, but users may not understand what contributes to that score or which areas need attention.The goal is to make the health score more transparent, understandable, and actionable through an interactive details panel.
Proposed UI
When a user clicks on a repository's health score, a side panel opens with three views:
1. Breakdown View (Primary Focus)
The Breakdown view is the main focus of this proposal.
Instead of displaying only the overall score, this view would explain the individual factors contributing to the repository's health score.
Proposed Information
Example Categories
The categories should be based on the actual scoring system used by the project.
UI Reference
The proposed design shows how users can understand the factors contributing to the overall repository health score.
Why This Matters
A user should be able to answer:
The Breakdown view should provide that explanation without requiring users to inspect multiple separate sections.
2. Recommendations View
The Recommendations view would provide actionable suggestions based on the repository's available health metrics.
Example Recommendations
Recommendations should be based on actual repository data and clearly defined rules.
UI Reference
The proposed design shows how improvement suggestions could be presented in a dedicated view.
3. Raw Metrics View
The Raw Metrics view would show the underlying repository metrics used in the health score calculation.
Example Metrics
Activity
Issues
Pull Requests
Contributors
Maintenance
The final metrics should be based on the data actually used by the existing scoring implementation.
UI Reference
The proposed design shows how users could inspect the data behind the health score.
4. User Interaction Flow
The proposed interaction would work as follows:
Complete UI Reference
This screenshot demonstrates the proposed health score interaction and details panel.
5. Technical Considerations
This proposal focuses on improving how users explore and understand health score information. It does not propose creating a separate scoring system.
Before implementation, the existing health score calculation and data flow should be investigated.
Proposed Technical Approach
If the current scoring implementation only returns an overall score, it may need to expose additional component-level information for the Breakdown view.
The implementation should follow the existing project architecture and design system.
6. Scope and Priority
Primary Focus: Breakdown
The initial focus would be the interactive Breakdown view:
Supporting Views
These supporting views can be implemented based on available data, project requirements, and maintainer feedback.
7. Relationship to Existing Health Scorecard Work
I understand that Issue #222 proposes a Repository Health & Risk Scorecard.
This proposal focuses on the interactive user experience for exploring an individual repository's health score within the Repository Explorer.
The intention is to complement the existing scoring work by providing a clear way for users to understand the score and inspect its supporting information.
The proposed UI and implementation scope can be adjusted to align with the existing health score architecture.
8. Expected Outcome
The proposed feature would help users move from:
Overall Score → Breakdown → Supporting Metrics → Potential Improvements
This would make repository health scores easier to understand and provide users with more context about the factors affecting repository health.
Questions for Maintainers
Additional Context
No response
Code of Conduct