Skip to main content

Component Guidelines

Introduction​

Components are Jira's built-in mechanism for categorising and organising tickets. This document explains how to effectively use Components to enable powerful filtering, reporting, and tracking of feature evolution across our Digital INNK applications—ViSN, DI Admin, and associated systems.

Why Components matter:

  • Long-term Tracking: Monitor how specific features or areas evolve over multiple sprints
  • Powerful Filtering: Quickly find all tickets related to a specific module or feature
  • Accurate Reporting: Generate module-specific metrics and insights
  • Team Coordination: Enable teams to focus on their functional areas
  • Historical Analysis: Identify patterns and trends in specific parts of the system

What Are Components?​

Components are labels that categorise tickets by functional area, allowing you to:

  • Group related tickets across multiple sprints and epics
  • Track feature evolution over time within specific areas
  • Generate reports focused on particular modules or features
  • Filter backlogs by functional area for sprint planning
  • Identify hotspots - areas of the system requiring the most attention
  • Enable team ownership - assign component leads for accountability

Components vs. Labels vs. Tags​

Understanding when to use each:

FeatureComponentsLabelsEnvironment Tags (in title)
PurposeFunctional area categorisationFlexible tagging for any attributeBug location/priority indicator
Best ForModule/feature groupingCross-cutting concerns (tech-debt, ui-fix)Environment-specific issues
Multiple AllowedYesYesNo (single environment per ticket)
HierarchySupportedNot supportedNot applicable
ExampleV-Customer, Grey Fleetbug, tech-debt, customer-reported(Prod), (Dev:Tiger)

Component Naming Strategy​

Components should mirror application's functional structure, making it intuitive to categorise tickets.

High-Level Components​

Start with broad functional domains:

V-Customer
V-Supplier
V-Admin
Grey Fleet
Job Sheet
Enquiry Management
Invoicing
Reports
API
Infrastructure

Hierarchical Components​

For more granular tracking, use hierarchical components with the > delimiter:

Grey Fleet > Add Driver
Grey Fleet > Add Vehicle
Grey Fleet > Vehicle List
Enquiry Management > Authorization
Enquiry Management > Job Lines
Reports > Compliance
Reports > Financial
API > V-Customer
API > V-Supplier

Component Hierarchy Example​

V-Customer (High-level module)
├── Grey Fleet (Feature area)
│   ├── Grey Fleet > Add Driver (Specific function)
│   ├── Grey Fleet > Add Vehicle (Specific function)
│   └── Grey Fleet > Vehicle List (Specific function)
├── Sub-Customer (Feature area)
│   ├── Sub-Customer > Management (Specific function)
│   └── Sub-Customer > Reporting (Specific function)
└── Compliance (Feature area)
    ├── Compliance > Scoring (Specific function)
    └── Compliance > Alerts (Specific function)
Naming Convention

Use the same naming convention as ticket titles: consistent delimiters (>) and clear, descriptive names that match your module structure.

Guidelines for Using Components​

Follow these best practices to maintain an organized and useful component system:

✅ Do❌ Don't
Attach multiple components when tickets span functional areasCreate a new component for every minor feature
Use existing components whenever possibleCreate duplicate or overlapping components
Match components to your module structure in codeUse components for environment tracking (use labels or title tags instead)
Think about long-term reporting needsCreate temporary components for a single sprint
Keep component names consistent with title conventionsUse different naming patterns for components vs. titles
Consult with team lead before creating new componentsCreate components without team discussion
Archive obsolete components when features are deprecatedDelete components (maintain history by archiving)
Use hierarchical components for subsections (Feature > Subfeature)Create flat components for every screen or modal

Decision Framework: Creating New Components​

Before creating a new component, ask yourself these questions:

The Four-Question Test​

Component Strategy

Think twice before creating a new component. Use this framework:

  1. Longevity: Will this component be used for multiple tickets over time?

    • ✅ Yes: "Grey Fleet" (ongoing feature area)
    • ❌ No: "Sprint 43 Cleanup" (temporary)

  2. Distinctiveness: Does it represent a distinct functional area worth tracking separately?

    • ✅ Yes: "Job Sheet" (specific feature with its own workflows)
    • ❌ No: "Add Button" (too granular)

  3. Alternatives: Is there an existing component that could work instead?

    • ✅ Check: Review existing components first
    • ❌ Don't: Create "Grey Fleet Vehicles" if "Grey Fleet" exists

  4. Reporting Value: Will this help with future reporting and analysis?

    • ✅ Yes: Component enables tracking feature evolution
    • ❌ No: Better suited for a label or description field

When to Create a New Component​

Create a new component when:

  • A new major feature or module is being developed
  • An existing area grows complex enough to warrant subsections
  • You need to track work in a distinct functional domain over time
  • Multiple teams need to coordinate around a specific area
  • Reporting requirements demand separate tracking

Examples of good reasons:

✅ New feature: "V-Customer > Onboarding" (new user onboarding flow)
✅ Growing complexity: "API > V-Customer" (API calls growing significantly)
✅ Team ownership: "Infrastructure > Monitoring" (dedicated DevOps focus)

When NOT to Create a New Component​

Don't create components for:

  • Temporary initiatives (use labels: quick-win, refactor-2024)
  • Environment tracking (use title tags: (Dev:Tiger), (Prod))
  • Issue types (already tracked by Jira issue type)
  • Sprint-specific work (tracked by sprint field)
  • Individual screens or modals (too granular)

Examples of poor component choices:

❌ Sprint 43
❌ Production Bugs
❌ Q4 2024 Goals
❌ Add Vehicle Modal (too specific)
❌ Dev Environment (use labels/tags)

Multi-Component Tickets​

Some tickets touch multiple functional areas and benefit from multiple components. This ensures visibility across all relevant teams.

Example 1: Cross-Module Feature​

Ticket: API > V-Customer > Book-In > Standardise error response format

Components:
- API (affects all API endpoints)
- V-Customer (affects customer-facing APIs)
- API > Book-In (specifically impacts Book-In API)
- V-Customer > Book-In (impacts Book-In regardless of entry point)

Why multiple components?

  • Different teams monitor different components
  • Enables finding this ticket from multiple perspectives
  • Provides complete picture in module-specific reports

Example 2: Infrastructure Change​

Ticket: Tech > ViSN > Database > Add composite index on enquiry_status and created_date

Components:
- Infrastructure (database work)
- V-Customer (impacts customer enquiries)
- V-Supplier (impacts supplier enquiries)
- Performance (optimization work)

Why multiple components?

  • Infrastructure team tracks all database changes
  • Feature teams see how it affects their modules
  • Performance team tracks optimization efforts

Example 3: UI Consistency Fix​

Ticket: ViSN > Design System > Standardize button styling across all modules

Components:
- Design System
- V-Customer (has buttons affected)
- V-Supplier (has buttons affected)
- V-Admin (has buttons affected)

Why multiple components?

  • Design System team owns the change
  • All affected modules are alerted
  • Each team can track UI updates in their area

Component Configuration in Jira​

Configure your Jira project with this hierarchical structure:

Components:
├── V-Customer
│   ├── Grey Fleet
│   │   ├── Grey Fleet > Add Driver
│   │   ├── Grey Fleet > Add Vehicle
│   │   └── Grey Fleet > Vehicle List
│   ├── Sub-Customer
│   │   ├── Sub-Customer > Management
│   │   └── Sub-Customer > Reporting
│   └── Compliance
│       ├── Compliance > Scoring
│       └── Compliance > Alerts
├── V-Supplier
│   ├── Job Sheet
│   │   ├── Job Sheet > Job Lines
│   │   └── Job Sheet > Pricing
│   ├── Enquiry Management
│   │   ├── Enquiry Management > Authorisation
│   │   └── Enquiry Management > History
│   └── Authorisation
│       ├── Authorisation > Approval Workflow
│       └── Authorisation > Permissions
├── V-Admin
│   ├── User Management
│   │   ├── User Management > Invitations
│   │   └── User Management > Roles
│   ├── Configuration
│   │   ├── Configuration > System Settings
│   │   └── Configuration > Feature Flags
│   └── Reports
│       ├── Reports > Financial
│       └── Reports > Operational
├── API
│   ├── API > V-Customer
│   ├── API > V-Supplier
│   └── API > Authentication
└── Infrastructure
    ├── Infrastructure > Database
    ├── Infrastructure > Deployment
    └── Infrastructure > Monitoring

Reporting with Components​

Components unlock powerful reporting capabilities:

Useful Component Reports​

  1. Velocity by Component: Track work completed per module per sprint
  2. Bug Density: Identify which components have the most bugs
  3. Time to Resolution: Compare resolution times across components
  4. Component Growth: See which areas are growing fastest
  5. Cross-Component Dependencies: Identify tickets spanning multiple areas

Example JQL Queries​

All open V-Customer tickets:

project = ViSN AND component = "V-Customer" AND status != Done

Bugs in Grey Fleet from last sprint:

project = ViSN AND component = "Grey Fleet" AND type = Bug AND sprint = "Sprint 43"

Cross-component API work:

project = ViSN AND component in ("API", "V-Customer", "V-Supplier") AND status = "In Progress"

High-priority infrastructure issues:

project = ViSN AND component ~ "Infrastructure*" AND priority in (High, Critical)

Component Maintenance​

Regular Review Cadence​

Quarterly Component Review:

  • Identify unused or rarely-used components
  • Consolidate overlapping components
  • Archive deprecated components
  • Create new components for emerging areas
  • Update component descriptions

Sprint Retrospective:

  • Discuss if tickets were properly categorised
  • Identify missing components
  • Address component confusion

Archiving vs. Deleting Components​

Archive (recommended):

  • Maintains historical data and reporting
  • Tickets retain component associations
  • Can be reactivated if needed

Delete (not recommended):

  • Loses historical associations
  • Breaks existing reports
  • Cannot be undone
Component Deletion

Never delete a component that has been used on tickets. Always archive instead to preserve historical data and reporting accuracy.

Common Mistakes to Avoid​

Mistake 1: Too Many Components​

Problem:

❌ Grey Fleet > Add Driver > Name Field
❌ Grey Fleet > Add Driver > Email Field
❌ Grey Fleet > Add Driver > Phone Field

Solution:

✅ Grey Fleet > Add Driver (sufficient granularity)

Mistake 2: Inconsistent Naming​

Problem:

❌ v-customer (lowercase)
❌ V_Customer (underscore)
❌ Customer Module (different format)

Solution:

✅ V-Customer (consistent with title guidelines)

Mistake 3: Using Components for Environments​

Problem:

❌ Component: "Production"
❌ Component: "Development"
❌ Component: "Staging"

Solution:

✅ Use title tags: (Prod), (Dev:Tiger)
✅ Or use labels: prod-bug, dev-environment

Mistake 4: No Component Governance​

Problem:

  • Anyone creates components without discussion
  • Duplicate components proliferate
  • No clear ownership or standards

Solution:

  • Require team lead approval for new components
  • Document component strategy
  • Regular component hygiene reviews

Integration with Agile​

Sprint Planning​

Use components to:

  • Filter backlog by team ownership
  • Balance work across functional areas
  • Identify cross-team dependencies

Example:

"Let's pull V-Customer tickets for this sprint, but we need API team support 
for the Grey Fleet > Add Driver work since it has both components."

Best Practices Summary​

✅ Do:

  • Mirror your application's functional structure
  • Use hierarchical components for subsections
  • Attach multiple components when appropriate
  • Consult team before creating new components
  • Archive (don't delete) obsolete components
  • Assign component leads for accountability
  • Use components for functional categorization

❌ Don't:

  • Create components for temporary work
  • Use components for environment tracking
  • Create overly granular components
  • Mix naming conventions
  • Create components without team discussion
  • Delete components with historical data

Quick Reference​

Component Decision Tree​

Need to categorise a ticket?
│
├─ Is it environment-specific? → Use title tag: (Prod), (Dev:Tiger)
├─ Is it a cross-cutting concern? → Use label: tech-debt, ui-fix
├─ Is it temporary/sprint-specific? → Use label: sprint-43, cleanup
└─ Is it a functional area? → Use component: V-Customer, API
    │
    ├─ Existing component available? → Use it
    ├─ Subsection of existing component? → Create hierarchical: Grey Fleet > Add Driver
    └─ New functional area? → Discuss with team, then create

Component Checklist​

Before creating a new component, verify:

  • No existing component covers this area
  • Will be used for multiple tickets over time
  • Represents a distinct functional area
  • Matches title naming conventions
  • Has been discussed with team lead
  • Adds reporting/tracking value
  • Not environment, sprint, or issue-type specific
Status: Approved
Category: Protected
Authored By: Vishwa Kumar
Last Updated: November 11, 2025
Version: 1.0
Revisions