Source-linked AI summary
Ritgard: T(r)opical Islands of Socio-Technical Artifacts on GitHub
Adam Štěpánek, Marco Raglianti, Jan Byška, Barbora Kozlíková, Michele Lanza
TL;DR
Project knowledge is fragmented across natural-language socio-technical artifacts that reveal architecture, decisions, and evolution beyond source code. RITGARD mines GitHub Issues, Pull Requests, and Discussions, organizes them into topic-based 3D islands with tree glyphs, and visualizes activity over time. The resulting landscape provides a high-level view of project discourse and evolution for interactive exploration.
Problem
Socio-technical artifacts contain project insights unavailable in source code, but fragmentation across channels and natural-language content makes them difficult to extract and explore.
Method
RITGARD mines GitHub socio-technical artifacts, applies topic modeling and processing, and renders topic islands, artifact trees, and activity-based terrain in an interactive 3D visualizer.
Results
RITGARD produces a high-level overview of project socio-technical artifacts that captures both the current state and the project’s evolution.
Takeaways & Limitations
The visualization can serve as a practical companion for engineers and users seeking to understand project discourse and key non-functional implications.
Abstract
from arXiv · showhide
A software project is more than just code. Non-code artifacts often document the human processes and decisions behind source code. The rationale behind a library change, an architectural decision, a problem encountered by a user are all examples of information typically present in socio-technical artifacts (STAs), created and persisted in channels separate from the repository itself (yet sometimes very close---e.g., GitHub Issues with GitHub repositories). These STAs are a trove of information about the project's architecture and its evolution, containing details and insights that code alone cannot provide. Unfortunately, this information is not easily extracted and explored as STAs are frequently fragmented over different communication channels, and are written in natural language. We present Ritgard, a tool that mines GitHub repositories for their STAs, namely Issues, Pull Requests, and Discussions, and visualizes them as 3D islands covered with trees. Each tree represents a single artifact and each island is a topic extracted from the artifacts through a combination of text embedding and text summarization. The terrain of the islands rises out of the ocean as the topic becomes active and sinks back in when it becomes stale, thus depicting the evolution of features and concerns throughout the project's lifetime. We describe the tool's usage and implementation, showing the numerous technical challenges behind Ritgard's visualization.
I. INTRODUCTION
Socio-technical artifacts document a software project’s processes, decisions, evolution, and community discourse beyond what code reveals. RITGARD addresses their fragmentation and natural-language complexity by combining mining, semantic analysis, summarization, and interactive 3D visualization.
- Non-code artifacts describe a project’s shape, history, development processes, architectural decisions, and community reception across volatile communication channels.
- GitHub Issues, Pull Requests, and Discussions serve distinct socio-technical roles spanning feature requests, code review, and developer-user discussion.
- Understanding socio-technical artifacts benefits developers, project managers, and users, but their volume, fragmentation, and natural-language form make them difficult to explore.
- RITGARD mines GitHub socio-technical artifacts and represents topics as 3D islands and individual artifacts as trees for high-level exploration.
II. RELATED WORK
Prior work analyzes individual socio-technical artifacts, artifact types, or source-code themes, while existing GitHub views do not provide a holistic overview. RITGARD responds to this gap with a topic- and evolution-oriented visualization of multiple artifact types.
- Existing tools and research emphasize broad usage of artifact types or deep analysis of individual socio-technical artifacts rather than holistic overview.
- Studies examine PR acceptance, Discussion guidelines, contributor-oriented issue recommendation, and topic modeling for GitHub Issues.
- Prior visualizations represent issue lifecycles or source-code themes, but issue tales disregard contents and topics while thematic maps exclude socio-technical artifacts.
- GitHub’s native tabular interface provides item details but is textual, paginated, and unsuitable for a holistic high-level overview.
III. T(R)OPICAL ISLANDS
RITGARD combines GitHub artifact mining and processing scripts with 3D t(r)opical-island visualization to summarize project discourse and its evolution. The prototype supports interactive exploration for developers and other stakeholders.
- RITGARD covers the pipeline from GitHub mining through preprocessing, topic modeling, terrain generation, rendering, and user interaction.
- The tool visualizes a high-level snapshot of project discourse and supports interactive exploration of its evolution.
- Although aimed mainly at developers, RITGARD can also support project managers and prospective adopters assessing maturity, non-code assets, and recurring issues.
A. Visualization Design
RITGARD maps GitHub socio-technical artifacts into a navigable 3D landscape where islands represent topics, tree forms identify artifact types, and terrain height depicts activity over time. Users can inspect artifacts and shift the visualized time window.
- Visualization Design: Each tree represents one artifact, islands group artifacts by prevailing topic, and distances between trees encode semantic similarity.
- Visualization Design: Terrain height corresponds to artifact activity, with heavily discussed Issues forming taller hills and unanswered Discussions remaining near sea level.
- Visualization Design: Conical, ball-top, and cube-top trees identify Issues, Pull Requests, and Discussions, while treeless stubs represent closed artifacts.
- Visualization Design: Artifacts without a prevailing topic become outliers placed on solitary voxel-based rocks.
- Visualization Design: Users can roam the landscape, open artifacts in a browser, and move or resize the sliding time window to examine different periods.
B. User Interface
RITGARD separates mining, processing, and terrain generation into scripts whose outputs feed a minimal interactive GUI. The interface supports inspecting STAs and adjusting the displayed dataset, terrain, trees, and time window.
- Interface structure: RITGARD’s mining, processing, and terrain-generation scripts feed a GUI with a status bar and side panel.The scripts expose a command-line interface configured through arguments and options.
- Interface structure: The hover bar displays the name and basic information for the STA or topic under the pointer.
- Interface structure: When no object is hovered, the interface shows the current visualization time and basic statistics for the view.
- Configuration: The side panel lets users select datasets, hide trees, hide closed-STA stubs, and normalize terrain height.These controls can emphasize height differences or limit occlusion.
- Interaction: Mouse and keyboard shortcuts support interaction, while the intentionally minimal GUI keeps attention on evaluating the visualization design.A cheatsheet for the shortcuts is included in the replication package.
C. Architecture and Pipeline
RITGARD uses a three-stage pipeline that mines GitHub STAs, processes their text into topic and terrain data, and renders an interactive landscape. The stages are distributed across tools and hardware because GitHub access, embedding computation, and visualization have different requirements.
- Pipeline: RITGARD’s pipeline mines a repository, embeds and clusters STA text, generates terrain data, and renders the result interactively.The three stages are data mining, data processing, and rendering.
- Data mining: GitHub mining uses REST for Issues and Pull Requests and GraphQL for Discussions, making strict API rate limits a potential bottleneck for large repositories.
- Data processing: Processing removes links and Markdown, embeds configurable STA content, reduces embeddings with UMAP, clusters them with HDBSCAN*, and names clusters with an LLM.The embedded content can include titles, labels, bodies, and comments, with non-title elements optionally excluded.
- Terrain generation: Terrain generation triangulates STA positions, interpolates and blurs heightmaps, and precomputes configurable sliding-window steps to reduce runtime computation.This tradeoff limits windows to predefined lengths while allowing the visualizer to move through project history at a reasonable pace.
- Rendering: The Godot visualizer renders processed landscapes and handles interaction using modern rendering APIs and dedicated-GPU capabilities.
- Deployment constraints: The pipeline is intentionally fragmented because mining needs sensitive GitHub tokens, topic modeling may need high-end GPUs, and visualization needs neither.Different stages can therefore run on different machines.
IV. EXAMPLES
Four same-scale snapshots compare two years of STA activity across projects A–D. Differences in size, terrain, activity, tree types, and submerged landmasses reveal contrasting project histories and communication practices.
- Comparison setup: The examples use the same two-year period, from June 2024 to June 2026, and the same image scale for comparison.
- Projects A–D: Project A is the most active and youngest example, combining the largest size and tree count with no submerged landmasses.The absence of submerged landmasses indicates creation within the visualized time span.
- Projects A–D: Projects B and C are similarly sized command-line utilities, but B has been considerably more active recently, with several topic-islands above sea level.
- Projects A–D: Projects C and D have similar activity levels, while D contains many more PR trees, suggesting its issues are likely discussed elsewhere.
- Communication channels: Only A and B show cube-top trees associated with Discussions, indicating that the other projects lack or have not enabled that feature.
V. CONCLUSION & FUTURE WORK
RITGARD addresses the difficulty of accessing GitHub socio-technical artifacts by combining topic modeling with 3D visualization to show their topics and evolution. Future work targets richer metadata, easier use, and smaller models for affordable hardware.
- Conclusion: GitHub Issues, Pull Requests, and Discussions capture lifecycle events, developer decisions, and user struggles that source code cannot convey.
- Conclusion: RITGARD combines topic modeling and 3D visualization to produce a high-level overview of a project’s socio-technical artifacts and evolution.
- Conclusion: The tool is presented as a potential practical companion for engineers and users seeking to understand key non-functional implications after further refinement.
- Future work: Future work will add STA metadata, polish the visualizer, refactor the pipeline into a client-server setup, and test smaller embedding and language models.The stated goal is to reduce entry barriers and identify models that perform well on affordable hardware.
- Reproducibility: The tool, demonstration video, and example datasets are available in a replication package for verifiability.