DOCSEARCHbyAlgolia
Submit Docs

jiratui

repository·main·Indexed 21 days ago

https://github.com/whyisdifficult/jiratui

A Text User Interface (TUI) and CLI tool for interacting with Atlassian Jira Cloud and Data Center from the terminal. Built with Textual and Rich, it allows users to search, update, and delete work items, manage comments, and search for users. It features a comprehensive TUI with specialized widgets for Jira field types and a CLI for direct resource interaction.

Tokens
47.2K
Snippets
64
Records
278
Agent score
82%

What's inside jiratui

  2. Understand the JiraTUI codebase structure

    main

    The JiraTUI codebase is organized into several functional modules located under src/jiratui/. Understanding this structure helps in locating specific logic for API interactions, UI components, or CLI commands:

    • api: Contains the core Jira API implementation classes and functionality.
    • api_controller: Manages classes and functionality related to the API controller.
    • widgets: The primary module for UI components. It includes submodules for specific features like attachments, comments, work_item_details, etc.
    • widgets.commons: A collection of reusable widgets and functionality intended for use across multiple modules.
    • commands: Defines the handler and render classes used by the CLI application.
    • css: Contains .tcss files used for styling the UI components.
    • utils: A collection of common utility classes and functions.
    • jtsite: Contains the source files for the public website (jiratui.sh).

  5. Use the Go-To feature to navigate related work items

    main

    The Go-To feature allows you to quickly jump to items related to a currently selected work item (such as its parent or subtasks).

    To access the Go-To screen, select a work item and press the f6 key. This shortcut is available in three locations:

    1. The search results table.
    2. The Related tab (list of related tasks).
    3. The Subtasks tab.

    Once the Go-To screen is open, it automatically fetches and populates data tables containing the item's details, its parent, and its subtasks.

  6. How project, issue type, status, and user filters interact

    main

    The four primary filters at the top of the application are linked to ensure valid selections:

    • Projects: Selecting a project automatically updates the available Issue Types, Status Codes, and Users.
    • Issue Types: If a project is selected, only types applicable to that project are shown. If no project is selected, all known types are shown (which may result in duplicate names across different projects).
    • Status Codes: If a project is selected, only statuses applicable to that project's issue types are shown.
    • Users (Assignee): Users are filtered by name or email. If a project is selected, the list is further restricted to users associated with that project's key.

    Project Visibility: A project appears in the list only if the user has one of the following Jira permissions:

    • Browse Projects
    • Administer Projects
    • Administer Jira (global)

    Configuration:

    • default_project_key_or_id: If set with a case-sensitive project key, JiraTUI will only fetch and load that specific project instead of all available projects.

  8. Choose the correct Jira REST API version

    main

    JiraTUI supports three distinct API versions depending on your Jira environment and requirements.

    • Jira Cloud Platform API v3: The recommended version for Jira Cloud. It supports Atlassian Document Format (ADF) for rich text formatting in descriptions and comments.
    • Jira Cloud Platform API v2: A legacy option for Jira Cloud. It uses the same endpoints as v3 but lacks ADF support.
    • Data Center v7.6.1: Used for on-premises (Jira DC) installations. Note that the endpoints and available operations differ significantly from the Cloud versions, and Atlassian is deprecating Data Center products.

  9. Understand the JiraTUI UI component structure

    main

    JiraTUI is organized into several distinct functional screens and views. Understanding these views helps in navigating the application and knowing where specific work item data is located:

    Navigation & Search

    • Main Screen: The entry point of the application.
    • Search Results: The view used to display the list of issues returned from a search query.

    Work Item Views

    When viewing a specific work item, the information is partitioned into several specialized tabs/components:

    • Work Item Information: Displays text-based fields.
    • Work Item Details: Displays key metadata and details.
    • Work Item Comments: Displays the history of comments.
    • Work Item Web Links: Displays associated web links.
    • Work Item Related Tasks: Displays linked or related tasks.
    • Work Item Subtasks: Displays child tasks/subtasks.
    • Work Item Attachments: Displays files attached to the item.

    Action Screens

    Specific workflows are handled by dedicated screens:

    • Create Work Item Screen: For generating new issues.
    • Add Comment Screen: For adding new comments to an existing issue.
    • Attach Files Screen: For uploading files to an issue.
    • Relate Work Items: For establishing relationships between two existing work items.

  10. Understand the JiraTUI UI Component Architecture

    main

    JiraTUI's UI is built using a hierarchical structure of widgets and screens, primarily leveraging the textual framework. The architecture follows a pattern where specialized Screen objects (like AddWorkItemScreen or WorkItemWorkLogScreen) manage complex user flows, while Widget components (like IssueDetailsWidget or RelatedIssuesWidget) handle specific data displays or input tasks.

    Key architectural patterns include:

    • Screens for Workflows: High-level tasks (adding a comment, creating a work item, logging time) are encapsulated in dedicated Screen classes.
    • Widget Composition: Complex views like IssueDetailsWidget are composed of multiple specialized field widgets (e.g., LabelsWidget, MultiSelectWidget, DateInputWidget).
    • Collapsible Components: For managing lists of related items (comments, links, subtasks), the UI uses collapsible patterns (e.g., CommentCollapsible, IssueRemoteLinkCollapsible) to manage vertical space.

  11. Important considerations for the docs directory

    main

    The docs directory contains a symlink to src/jiratui. This allows Sphinx to parse the codebase and generate documentation from Markdown syntax inside docstrings.

    Developer Precautions:

    • IDE Indexing: Exclude the docs directory from your IDE's indexing to prevent performance issues or indexing errors.
    • Module Imports: Do not import modules from the docs directory when using IDE or AI code suggestions; always import from the actual source directory.

  12. Understand the JiraTUI architecture

    main

    JiraTUI is composed of two primary interfaces that interact with the Atlassian Jira API via a shared backend logic layer.

    Core Components

    • API Controller: The central logic layer that provides functionality for managing Jira resources.
    • API: Implements the Jira REST API endpoints and handles communication with the Atlassian Jira API (Cloud or Data Center) via HTTPS.

    Interface Modes

    1. CLI Application: A command-line interface built with click. It is useful for interacting with specific resources (like comments and issues) or debugging Jira interactions by retrieving metadata required for work items.
    2. UI Application: A Terminal User Interface (TUI) built using the Textual framework, Rich, and asyncio. It provides a rich, widget-based interface for complex Jira workflows.