A Python GUI for tracking open-source project issues

Maintaining an open-source project means keeping several kinds of information in view at once: bug reports, feature requests, release notes, security concerns, pull requests, and unanswered questions. A browser tab for each repository works for a while, but it quickly becomes noisy when a developer supports several utilities with different release rhythms.

The aim is straightforward: building a Python GUI to track my open-source project issues without turning maintenance into another web dashboard. A small desktop application can collect the information that matters, display it clearly, and remain useful when working offline or switching between projects.

This approach suits a portfolio containing practical Linux and Python tools. A security utility such as DenyHosts may need attention for a vulnerability report, while a regular expression debugger such as Kodos may have older compatibility requests waiting quietly in the queue. A log analyser can have an entirely different set of maintenance signals.

For Australian developers, the desktop model has a few practical advantages. A maintainer in Perth may be working several hours away from contributors in Melbourne or Sydney, and an issue tracker should make priority visible without relying on a live meeting. During a busy arvo, a compact local window is often quicker than sorting through multiple browser tabs.

Choosing a simple Python desktop stack

Tkinter is a sensible starting point because it ships with most standard Python installations and has a low barrier to entry. It can provide windows, forms, menus, tree views, buttons, and status areas without adding a large dependency chain to a small open-source project. For a utility intended to run on Linux, that restraint is valuable.

The interface can use a left-hand project list, a central issue table, and a detail panel. Each project could show its name, repository location, current version, and the date of its last review. Selecting an issue would reveal its title, labels, discussion notes, assigned person, and proposed action.

A more polished interface could use PySide or PyQt, particularly if the application needs richer filtering, native-looking controls, or a model-view architecture. The trade-off is packaging and licensing complexity. For a personal portfolio tool, Tkinter keeps the first release easier to install and explain.

Designing the issue data model

The application needs a stable internal record rather than a collection of widgets with hidden state. A small SQLite database is a good fit. It can store projects, issues, labels, activity dates, notes, and synchronisation details in one portable file. JSON export would provide a useful backup and migration path.

A project record might include a repository URL, local checkout path, language, licence, and maintenance status. An issue record could contain an external identifier, title, body summary, state, priority, labels, author, creation date, update date, and a link back to the original discussion. Keeping the external identifier prevents duplicate imports.

The model should distinguish between “open upstream”, “being investigated”, “fixed locally”, and “released”. Those states describe a maintainer’s workflow more accurately than a basic open-or-closed flag. A security issue in an SSH protection tool deserves different treatment from a minor display defect in a log analyser.

The portfolio context also benefits from clear project boundaries. A developer can review the background and active work behind these kinds of tools through Phil’s project portfolio, then mirror that separation in the application rather than presenting every issue as one undifferentiated queue.

Pulling issues into a local queue

A synchronisation layer can fetch issues from a hosting service through its API, then convert the response into the local data model. The first run should ask for project details and credentials, while later runs can use a saved configuration. Personal access tokens belong in the operating system’s credential store or an environment variable, never in the SQLite file.

Rate limits and temporary network failures need careful handling. The GUI should show whether a refresh completed, failed, or partially succeeded. A local cache means the issue list remains available on a train, during an NBN outage, or while travelling between regional towns. The user should still be able to add notes and change local priorities offline.

Australian time zones deserve attention in activity displays. A timestamp from a contributor in UTC can be confusing when a maintainer is reading it in AEST, ACST, or AWST. Storing dates in UTC and rendering them in the user’s selected zone avoids misleading “last updated” values, especially when a Perth contributor and a Sydney contributor are working on the same patch.

Making the interface useful at a glance

The issue table should answer three questions quickly: what needs attention, why it matters, and what happens next. Useful columns include project, title, priority, age, labels, and current state. Colour can help, but text labels and sorting must carry the meaning for users with visual impairments or monochrome terminals.

Filters should cover project, state, priority, label, age, and assigned person. A saved view called “release blockers” could combine several conditions, while another view could display stale issues that have received no activity for 90 days. Search should cover both titles and notes, since maintainers often remember a phrase from a discussion rather than an issue number.

A detail panel can include a short maintenance note such as “reproduce on Python 3.12” or “check Debian package behaviour”. This turns the GUI into a working memory aid rather than a passive mirror of a web service. Keyboard shortcuts for refresh, search, status changes, and opening the upstream issue would make repeated triage faster.

Features worth shipping first

A first release should solve the daily triage problem before adding charts, notifications, or elaborate project analytics. The following features provide a useful baseline:

• Import issues from one or more repositories with duplicate detection.
• Store local priorities, notes, labels, and workflow states in SQLite.
• Filter by project, status, age, label, and release relevance.
• Open the upstream issue in a browser and copy its identifier quickly.
• Export a plain-text or JSON maintenance report for release planning.

The application should also record a short audit trail for local changes. If a priority is raised or an issue is marked as a release blocker, the maintainer can later see why that decision was made. This is particularly handy for small Australian teams where one person may handle support in Brisbane while another checks patches after hours in Adelaide.

Packaging is part of the project, not an afterthought. A clear README, a sample database, platform notes, and a small test suite can make the tool approachable for contributors. PyInstaller may produce a convenient executable, while a normal Python package remains preferable for Linux users who want transparent installation and easy inspection.

Testing, distribution, and long-term maintenance

The core logic should be testable without starting the GUI. Tests can cover database migrations, issue merging, time-zone conversion, filtering, export, and API error handling. GUI tests can then focus on a smaller number of interactions, such as selecting a project, refreshing data, and editing a local note.

A mock API is essential for repeatable tests. It can simulate pagination, deleted issues, changed labels, rate limits, and malformed responses. This prevents development from depending on a live repository and avoids accidentally modifying real project data during testing.

Documentation should explain the data flow in plain language: where credentials live, when synchronisation occurs, which fields are local, and how to restore a backup. That clarity matters in the Australian open-source market, where a small consultancy or community group may need to assess a tool quickly before adopting it.

The strongest version of this project would remain modest, portable, and transparent. A Python GUI that turns scattered issue activity into a prioritised local queue can support several mature utilities without becoming another system that demands constant administration.