Azure TagDay & DevOps Management UI

A modern desktop application and Python automation suite for Azure DevOps / TFS project management, Git repository tracking, Tag Day readiness auditing, build artifact storage monitoring, and automated document generation.

---

Features

• Desktop GUI (PySide6 / QML): Fast, modern UI with dark mode, real-time TFS sync, repository categorization, active pull request tracking, work item search, and artifact storage visualizer.
• Agile Weekly Sprint Reports: Automated sprint reports for weekly iterations (week-YYWW), detailing velocity, completed vs active User Stories / Requirements, Bugs / Defects, and Technical Tasks with Markdown and CSV export.
• Team Workload & Capacity Explorer: Interactive calendar matrix visualizing team member workload across 4, 8, or 12 iterations (1 month, 2 months, 1 quarter) with real-time capacity heatmap and item drill-down drawer.
• Deadlines & Urgency Visualizer: Automatic milestone deadline detection with visual urgency countdown badges (🚨 Overdue, ⏳ Due This Week, 📅 Due Next Week, 🔮 Upcoming, ✓ Closed).
• Tag Day Audits & Reporting: Multi-view release readiness evaluation comparing repos against reference tags, analyzing unmerged branches, ahead/behind commit counts, and pull request activity.
• Build & Artifact Storage Analytics: Tracks build executions, container/file sizes, reclaimed space, and pipeline storage trends across SQLite databases.
• Automated Documentation: Generates REVISION.md / REVISION.docx tracking history, SPRINT_REPORT_<sprint>.md / .csv, and BUILD_ARTIFACTS.md / BUILD_ARTIFACTS.csv summaries.
• Local SQLite Caching: Offline-first architecture caching repositories, branches, tags, PRs, work items, builds, and artifacts.

---

Quick Start with uv

This project uses uv for Python environment and dependency management.

1. Prerequisites

Install uv (if not already installed):

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or via pip
pip install uv

2. Install Dependencies

Sync and install the project virtual environment automatically:

uv sync

---

Running the Application

Launching the Desktop GUI

You can launch the GUI using the integrated shortcut:

uv run gui

Or via direct script invocation:

uv run python src/gui/main.py

To run a headless smoke test:

uv run gui --test

Running CLI Tools & Automation

All CLI tools can be run seamlessly using uv run:

# Sync project data from Azure DevOps / TFS into local SQLite cache
uv run python src/devops_helper.py --sync

# Force fresh synchronization bypassing delay threshold
uv run python src/devops_helper.py --sync --force

# Generate the Tag Day release readiness report (TAGDAY.md)
uv run python src/devops_helper.py --report-tagday

# Generate build artifact storage reports (BUILD_ARTIFACTS.md & .csv)
uv run python src/devops_helper.py --report-artifacts

# Generate revision history document (REVISION.md and REVISION.docx)
uv run python src/devops_helper.py --revision

# Export pull requests to Excel and Markdown
uv run python src/devops_helper.py --export-prs PR_EXPORT

# Generate Agile weekly sprint report (Markdown & CSV)
uv run python src/generate_sprint_report.py --sprint week-2633

# Generate sprint report with custom output paths
uv run python src/generate_sprint_report.py --sprint week-2633 --out-md doc/SPRINT_2633.md --out-csv doc/SPRINT_2633.csv

---

Agile Weekly Sprints, Workload & Deadlines

1. Sprint Naming & Date Math (week-YYWW)

In our agile workflow, sprints follow a weekly sprint cycle identified by ISO calendar year and week number (e.g. week-2633 represents Year 2026, Week 33, running from Monday 2026-08-10 through Friday 2026-08-14).

• Automatic date range resolution (start_date, end_date, user-friendly range labels).
• Supports standard week-YYWW, week_YYWW, sprint-YYWW, and nested iteration paths like Project\week-2633.

2. Timeframe Reports (Markdown & CSV)

• KPI Metrics: Total Work Items, Stories/Requirements, Bugs/Defects, Technical Tasks, Completed vs Active counts, and overall Velocity completion rate (%).
• Functional Breakdown: Dedicated sections grouping User Stories / Requirements, Bugs Handled, and Tasks with linked PR counts.
• Team Contribution: Workload table listing total assigned items, stories, bugs, tasks, and completion rate per engineer.
• Export: Exports to GitHub-flavored Markdown wiki (SPRINT_REPORT_<sprint>.md) and flat semicolon-delimited CSV (SPRINT_REPORT_<sprint>.csv).
• Interactive UI: Integrated into the GUI under Reports & Analytics ➔ 🚀 Sprint Report.

3. Interactive Workload & Capacity Explorer

Accessible from the sidebar navigation (👥 Workload Explorer):

• Horizon Switcher: Toggle across 4 Sprints (1 Month), 8 Sprints (2 Months), and 12 Sprints (1 Quarter).
• Heatmap Capacity Matrix: Grid showing each team member (with avatar and total workload) against chronological sprint columns.
• Visual Breakdown: Cells indicate total count, stories (🎯), bugs (🐛), and overdue warnings (🚨), color-coded by workload density.
• Interactive Drill-Down: Click on any cell to open a slideout drawer displaying the full list of assigned work items with status badges, countdown urgency pills, and direct TFS links.

4. Deadlines & Urgency Visualizer

• Automatically resolves work item deadlines from configurable custom attributes (e.g. Custom.TargetMilestone, Microsoft.VSTS.Scheduling.TargetDate, DueDate, or FinishDate), falling back to sprint Friday milestone dates.
• In-App Deadline Editor: Click any deadline badge in Work Items or Workload Explorer to set a custom date or one-click preset ("Sprint End", "Today", "+1 Week", "+2 Weeks", "Clear"). Writes back directly to TFS via JSON-Patch REST API and updates local cache.
• Custom Attribute Configuration: Set your team's custom deadline attribute in Settings ➔ Work Item Deadline Attribute or config/user_settings.yaml.
• Dynamic Urgency Badges:
  • 🚨 <N>d Overdue: Highlighted in red when the milestone is in the past.
  • ⏳ <N>d left / ⚡ Due Today: Highlighted in amber when due within 7 days.
  • 📅 Next Wk (Mmm DD): Highlighted in blue when due within 8–14 days.
  • 🔮 Mmm DD: Neutral indicator for future deadlines.
  • ✓ Closed: Green completed badge.
• Table Filters: Filter by 🚨 Overdue, ⏳ Due This Week, 📅 Due Next Week, and 🔮 Upcoming in Work Items.

5. Sprint Rescheduling & TFS Web API Writeback

• Interactive Sprint Rescheduling: Reschedule any User Story or Bug directly in the GUI:
  • In Work Items: Click the Iteration column badge or context action.
  • In Workload Explorer: Click the 🔄 Sprint pill on any story card in the drawer.
• Sprint Picker Modal: Select from chronological sprint lists or quick presets ("+1 Sprint", "+2 Sprints", "Move to Backlog"). Automatically writes System.IterationPath back to TFS via Web API with immediate local cache update.

6. Iteration Shift & Postponement Impact Analysis

• Automatic Shift Tracking: Automatically logs iteration changes whenever a work item moves to a different sprint—both from manual GUI moves and during TFS synchronization.
• Delay & Postponement Metrics: Computes exact calendar week deltas between sprints (e.g. week-2631 ➔ week-2633 = +2 weeks delay).
• Impact Analysis Dashboard: Dedicated tab under Reports & Analytics ➔ ⏱️ Iteration Shifts:
  • KPIs: Total Shift Events, Rescheduled Items, Net Delay / Postponed Weeks, and Most Postponed Item.
  • Postponed Stories & Bugs Table: Identifies the most frequently delayed stories and cumulative postponement weeks.
  • Rescheduling Audit Log: Chronological stream of all sprint shifts with source badges (🖥️ GUI vs 🔄 Sync) and delta pills.
  • Visual Warnings: Work items in tables and cards display shift badges (e.g. ⚠️ Shifted +2w).

7. Typography Sizing & High-DPI Display Scaling

• Customizable Font Sizes: Easily switch text and UI scaling to match your monitor resolution:
  • Small (90%): Compact layout for dense information and small screens.
  • Medium (100% - Default): Balanced standard scale for 1080p monitors.
  • Large (115%): Enhanced readability and enlarged typography.
  • Extra Large (130%): High-DPI / 4K monitors and high-accessibility viewing.
• Quick Switcher: Click 🔤 Font: S | M | L | XL directly in the sidebar navigation without leaving your current view.
• Settings Card: Full configuration with visual descriptions under Settings ➔ Display & Typography Scaling.
• Persistent Preferences: Saves automatically in config/user_settings.yaml across application restarts.

8. Workload Parent Grouping & Configurable Bug Hierarchy

In the Workload Explorer, selecting a team member's cell groups tasks cleanly by parent container card rather than listing disjointed tasks:

• Parent Container Cards: Each User Story, Requirement, or Bug card shows title, status, deadline urgency badge, rescheduling action, and a nested list of child tasks with completion checkboxes and progress bars (X / Y tasks completed (Z%)).
• External Parent Resolution: When a child task is assigned to an engineer but its parent User Story is assigned to an architect/lead or scheduled in a different sprint, the parent card displays an External Parent badge with the parent's assignee.
• Standalone Tasks: Direct tasks with no parent link appear grouped under a clean Direct Tasks / Standalone Items container card.
• Configurable Bug Hierarchy Mode (Project & Global Settings):
  • Bugs as Stories (like_user_story): Bugs act as top-level backlog items that can contain individual tasks (standard Scrum/Agile workflow).
  • Bugs as Tasks (like_task): Bugs are child work items contained inside parent User Stories or Requirements.
  • Quick Toggle: Switch dynamically in the Workload Explorer header (🪲 Bugs: As Stories | As Tasks) or configure under Settings ➔ Bug Hierarchy & Workload Container Grouping (persisted in config/user_settings.yaml).

9. Major Milestones, Multi-day Events & Target:<Milestone> Tagging

Track strategic deadlines, external audits, quality gates, and release phases across all project views:

• Target:<Milestone> Work Item Tag Mechanism:
  • Assign any work item (Epic, Feature, User Story, Bug, Task) to a milestone in Azure DevOps / TFS by adding a tag formatted as:

    Target:<MilestoneName>
    

  • Tag Examples:
    • Target:DDQS-01 ➔ Internal Process Quality Gate (⚙️ DDQS)
    • Target:QIAV-GateA ➔ External Process Compliance (🔷 QIAV)
    • Target:Scenario_Bravo ➔ External Scenario Demo (🎬 Scenario)
    • Target:Release_2026.1 ➔ Internal Release (🚀 SW/FW)
    • Target:System_Freeze ➔ General Milestone (🏁 General)
  • Features: Case-insensitive matching (target: ddqs-01 = Target:DDQS-01), combinable with other tags separated by semicolons (Target:DDQS-01; Backend; Prio1).
• Auto-Discovery & Automatic Pre-filling:
  • During TFS synchronization, the app automatically scans cached work items for Target:<MilestoneName> tags.
  • New milestones are automatically created in the database with auto-inferred categories and target dates derived from the most frequent date among tagged work items.
  • Can also be triggered manually by clicking ⚡ Pre-fill from Work Items in the 🚩 Milestones manager dialog.
• Matching Precedence & Hierarchy Inheritance:
  1. Tag Match (Highest Priority): Matches explicit Target:<MilestoneName> tags.
  2. Date / Range Match (Fallback): Matches work items whose target date or deadline falls on the milestone date or within a multi-day event range [start_date, end_date].
  3. Inheritance: Child tasks inherit the milestone of their parent story/feature if not explicitly tagged.
• Multi-Day Events & Multi-Sprint Overlap:
  • Milestones support single-day deadlines or multi-day spans (e.g. 2-week testing window 2026-08-10 – 2026-08-21).
  • Automatically calculates duration in days and displays milestone chips across all overlapping sprint week columns in the Workload Explorer.
• Milestone Filter in Workload Explorer:
  • Top toolbar ComboBox supporting both dropdown selection and free-text editing / substring search:
    • All Milestones (ALL)
    • 🎯 Planned (Has Milestone) (PLANNED)
    • ⚪ Unplanned (No Milestone) (UNPLANNED)
    • Specific milestone names or custom typed substrings (e.g. DDQS, Alpha, QIAV).
  • Includes a quick 1-click clear button (✖).
• Milestones Manager Dialog:
  • Accessible via the 🚩 Milestones header button to create, edit, customize colors and icons, set date ranges with calendar pickers and duration presets (+1 Day, +2 Days, +1 Wk, +2 Wks), and delete milestones.

---

Running Tests

Execute the full automated unit test suite with uv:

# Run all unit tests
uv run python -m unittest discover -s src/tests

# Or using the built-in runner script
uv run python src/tests/run_tests.py

# Run sprint and deadline tests specifically
uv run python -m unittest src/tests/test_sprint_workload_and_deadlines.py

---

Building Executables & Installers

1. One-Click Build (Executable + Setup Installer + Wheel)

Run the automated build orchestrator:

uv run python build_installer.py

This script will automatically:

1. Compile the PyInstaller bundle in dist/azure-tagday-ui/.
2. Compile the Windows Setup installer (dist/AzureTagDayUI-Setup-0.1.0.exe) using NSIS or Inno Setup.
3. Build the distributable Python wheel and source distribution (dist/*.whl, dist/*.tar.gz).

---

2. Standalone Desktop Executable (PyInstaller)

To compile the application bundle directly:

uv run pyinstaller --noconfirm azure-tagday-ui.spec

The output executable and bundled resources will be generated under: dist/azure-tagday-ui/azure-tagday-ui.exe

To smoke-test the built executable:

.\dist\azure-tagday-ui\azure-tagday-ui.exe --test

---

3. Windows System Installer (NSIS / Inno Setup)

The project includes two pre-configured installer scripts:

• NSIS: installer.nsi

  & "C:\Program Files (x86)\NSIS\makensis.exe" installer.nsi
  

  Produces dist/AzureTagDayUI-Setup-0.1.0.exe with desktop shortcut, Start Menu items, and Windows Uninstaller registration.

• Inno Setup: installer.iss

  & "C:\Program Files (x86)\Inno Setup 6\ISCC.exe" installer.iss
  

  Produces dist/AzureTagDayUI-InnoSetup-0.1.0.exe.

---

4. Distributable Python Packages (Wheel & Source Distribution)

To build standard .whl and .tar.gz packages:

uv build

The installable wheel can be installed into any environment via:

pip install dist/azure_tagday_ui-0.1.0-py3-none-any.whl

---

Configuration

Configuration files are centrally managed in the top-level config/ folder and optional root .env:

1. config/user_settings.yaml

Stores the active database connection, project selection, and recent databases:

db_path: C:\path\to\tfs_cache_MY_PROJECT.db
project_id: MY_PROJECT
project_name: MY_PROJECT
recent_databases:
  - C:\path\to\tfs_cache_MY_PROJECT.db

2. config/repo_categories.yaml

Maps repository names or prefixes to logical functional categories and display badge colors.

3. config/status_icons.yaml

Configures status indicator emojis, badge styles, and visual icon tokens.

4. Optional .env File

For headless/CLI sync, create a .env in the repository root:

AZURE_BASE_URL=https://tfs.example.local:8080/tfs
AZURE_COLLECTION=DefaultCollection
AZURE_PERSONAL_ACCESS_TOKEN=your_pat_token
AZURE_PROJECT_ID=MY_PROJECT

---

Project Structure

├── config/                      # Application and reporting configuration
│   ├── repo_categories.yaml     # Repository category definitions & colors
│   ├── status_icons.yaml        # Status badge & icon mappings
│   └── user_settings.yaml       # User database and project preferences (gitignored)
├── src/
│   ├── azure/                   # Azure DevOps REST client & SQLite cache layer
│   │   ├── azure_base_client.py # HTTP transport & authentication
│   │   ├── azure_db.py          # SQLite database engine (AzureDevOpsCache)
│   │   ├── azure_helper.py      # Timestamp formatting and date helpers
│   │   ├── azure_info_base_client.py # Low-level TFS REST client
│   │   └── azure_info_handler.py     # High-level domain aggregator
│   ├── gui/                     # Desktop GUI application
│   │   ├── backend.py           # PySide6 backend controller & QObject bridge
│   │   ├── main.py              # Application bootstrap & QML engine loader
│   │   ├── workers.py           # Background sync threads
│   │   └── qml/                 # QML views, components, and Theme
│   ├── tests/                   # Unit test suite
│   ├── devops_helper.py         # CLI orchestrator
│   ├── generate_artifacts_report.py # Build & artifact disk usage reporter
│   ├── generate_revision.py     # REVISION.md / .docx document generator
│   ├── generate_sprint_report.py # Agile weekly sprint & timeframe reporter
│   ├── generate_tagday_report.py    # Tag Day release audit reporter
│   └── utils.py                 # Core utilities & environment loaders
├── doc/                         # Comprehensive guides & documentation
│   └── BUILD.md                 # Building, Packaging & CI/CD guide
├── templates/                   # Jinja2 markdown report templates
├── pyproject.toml               # Project metadata and dependency definitions
└── uv.lock                      # Exact locked dependency versions

---

Packaging & Continuous Integration

For complete instructions on building Python wheels, compiling standalone Windows NSIS installers, dynamic git describe versioning, and configuring GitHub Actions CI/CD workflows, see the dedicated Building and Packaging Guide.