Skip to main content

Jira Software Guide: Managing Our Engineering Workflow

1. Introduction: The System of Record for Development​

While Jira Service Management (JSM) tracks our operational health, Jira Software is the system of record for all our software development activities. It's where we plan our sprints, manage our backlogs, and track the progress of every new feature, bug fix, and technical debt item from idea to deployment.

This guide details how we use Jira Software, including our standard project configuration, workflows, and how our AI agent, Sparky, automates ticket creation and management.

Core Mission: To use Jira Software to provide a clear, consistent, and transparent view of all work being done by the engineering teams, enabling effective agile development and cross-team collaboration.

2. Our Standard Project Configuration​

All engineering projects in Jira Software follow a standardized configuration to ensure consistency.

  • Boards: Each team has a primary Kanban board. We prefer Kanban over fixed-length sprints to allow for a continuous flow of work, which is better suited for our operational and responsive development style.
  • Issue Types: We use a defined set of issue types to categorize all work:
    • Epic: A large body of work that can be broken down into smaller Stories (e.g., "Implement Service Chain Monitoring").
    • Story: A new feature or user-facing improvement (e.g., "As a user, I want to see my SLOs on my dashboard").
    • Bug: A functional error in the product reported by a user or found during testing.
    • Task: A technical task that is not a user-facing story (e.g., "Upgrade database to version X").
    • Spike: A time-boxed research task to investigate a technical problem.
    • Vulnerability: A security issue, usually created automatically by FOSSA or a security scanner.
    • Performance: A ticket to address a performance issue, usually created by Sparky or an SRE.
  • Statuses (The Workflow): All issues move through a standard set of statuses, which are reflected as columns on our Kanban boards.

3. The Lifecycle of a Development Task​

This diagram shows the path a typical Story or Bug takes from creation to completion.

  1. To Do: The work is defined and in the backlog, ready to be picked up.
  2. In Progress: A developer has assigned the issue to themselves and is actively working on the code.
  3. In Review: The developer has finished the code and opened a Pull Request. The issue is now waiting for a peer review.
  4. Ready for Deploy: The PR has been approved and merged into the main branch. The automated CI/CD pipeline is running.
  5. Deployed: The code has been successfully deployed to production.
  6. Done: The developer has verified the fix or feature in production, and the work is considered complete.

4. Verbose Workflow: Sparky's Interaction with Jira​

Sparky is a key contributor to our Jira projects, acting as an automated SRE that creates detailed, context-rich tickets for issues that require human intervention.

Scenario: Sparky Creates a Performance Ticket​

  1. Detection: As described in the Performance Tuning guide, Cerebro detects a sustained, anomalous increase in memory usage in the recommendation-service. It's not critical enough for a P1 incident, but it's a memory leak that needs to be fixed.
  2. Sparky's Analysis: Cerebro hands off the analysis to Sparky. Sparky gathers all relevant information:
    • A link to the New Relic dashboard showing the memory trend.
    • A memory profile (profile.svg) captured using py-spy.
    • The specific service, deployment, and pod names affected.
    • The last 5 deployments for that service.
  3. Automated Ticket Creation: Sparky uses the Jira API to create a new issue in the recommendation-service team's project.

Example: The Ticket Sparky Creates​

Project: REC Issue Type: Performance Assignee: [Unassigned] Labels: sparky-generated, memory-leak

Title: Sparky: P90 Memory Usage for recommendation-service has increased by 50% over 24 hours

Description (Body):

### 🤖 Sparky Performance Report

**Summary:**
I have detected a sustained and anomalous increase in the P90 memory utilization for the `recommendation-service`. This pattern is consistent with a memory leak and requires investigation.

**Severity:** Medium (Not currently impacting customers, but will lead to OOMKills if unaddressed).

---

### Diagnostic Data

*   **📈 New Relic Dashboard:** [Link to New Relic dashboard showing memory trend](https://one.newrelic.com/...)
*   **📊 Memory Profile:** A flame graph from `py-spy` is attached to this ticket. It indicates that the majority of memory growth is occurring in the `build_recommendation_graph` function.
*   **Service:** `recommendation-service`
*   **Environment:** `production-us-east-1`
*   **Last 5 Deployments:**
    *   `abc1234` - *26 hours ago*
    *   `def5678` - *3 days ago*
    *   ...

---

### Suggested Action

Please investigate the `build_recommendation_graph` function for a potential memory leak. The leak appears to have started after deployment `abc1234`.

This ticket gives the developer everything they need to start investigating immediately, saving hours of diagnostic time.

5. Automation and Integration​

  • GitHub Integration: Our primary automation is the link between GitHub and Jira.
    • From Commit: Include a Jira issue key (e.g., PROJ-123) in your commit message to link the commit to the issue.
    • From PR: When you open a PR, include the issue key in the title. This automatically transitions the Jira ticket to In Review. When the PR is merged, the ticket moves to Ready for Deploy.
  • Slack Integration: Team channels are configured to receive updates on new and transitioned issues in their project, keeping everyone informed.