Jira Protocol
Contents:
Bug / Feature / Enhancement / User Story Jira Ticket Template
Note
Use best judgment to include screenshots / additional information as needed. User Stories should be written in the format of “As a _ user, I need to ___, because _”
The following template should be copied / pasted into the description of a Jira ticket:
## Overview / Rationale for This Ticket
## Actual Functionality [Possibly N/A for Features]
## Expected Functionality
## Steps to Reproduce [Possibly N/A for Features]
## Business Rules & Acceptance Criteria
## Documentation Updates
## Work Plan
### UI Changes Needed
#### User Focused Tests to Write
### API Changes Needed
#### API Test Coverage
### Database Changes
#### Data Preparation
### Blast Radius
#### What fragile / mission critical component are affected?
#### How dangerous are these changes?
### Deployment
#### Environment Configuration Changes
#### Rollback Plan
### External Dependencies
### Other Considerations
Ticket Work Plans
Most tickets require a written and approved work plan before engineering work begins. The purpose of the work plan is to ensure engineers critically assess the systems affected by a given feature or bug fix, and to anticipate any downstream impact.
While it may be tempting to use AI to draft a work plan, the intent is for engineers to first think deeply about the problem space. AI can be a valuable tool for stress-testing ideas or exploring alternative solutions, but it should serve as a second opinion—not the first draft. Relying solely on AI can introduce errors or assumptions that go unchallenged without a well-considered foundation.
Note
If you don't need a section, put N/A or something to that effect.
UI/UX Changes Needed
Describe any visual or interaction changes to the frontend. Are new components being introduced? Do existing views need layout or logic updates? Include links to or screenshots of design specs or mockups, if available.
User Focused Tests to Write
What User scenarios should we validate? Think of common user errors, misuses, or edge cases that might result in confusing behavior or incorrect system state.
API Changes Needed
What new endpoints are required? What existing endpoints should be updated? Are there any request or response models that need to be updated? Consider versioning, auth scopes, and backward compatibility.
Also note any new backend components that may be needed, such as handlers, scheduled jobs, repositories, or data access layers, utilities, services, validators, etc.
API Test Coverage
Which unit, integration, or contract tests should be added or updated to validate the above API changes?
Database Changes
Detail any schema updates, including new tables, columns, indexes, constraints, or relationships. Should this be handled in a single script or multiple?
What new stored procedures are required? Is there a reason these stored procedures can't or shouldn't be made into backend services instead?
Are there any special considerations that need to be made?
Data Preparation
Do we need to backfill, seed, or clean up existing data to support these changes? What tooling or scripts will be used, and how should they be run (manual, automated, idempotent)?
Blast Radius
Are any critical systems or processes affected by this change? What parts of the system could be affected by this change? Consider upstream/downstream services, shared components, and user-facing functionality. What’s the rollback plan if needed?
What fragile / mission critical component are affected?
Fragility is defined by a lack of test coverage and overall complexity of interconnected components. Symptomatically, these are areas of the application that always seem to result in bugs when changes are made.
Mission critical areas are defined as areas that are highly visible and required for the core functionality of the application. It also includes areas of the application where a bug could create a problem that we can't easily fix without hours upon hours of remedial work.
Good examples would be the email process in reporting hub or the interest calculation section of Partner Portal.
How dangerous are these changes?
Try and give us qualitative estimate of the danger. Think in terms of Critical, Severe, Moderate, Light, or None.
An example of a None would be fixing a typo on the front end. The likely worst case scenario is that we replace it
with another typo.
Deployment
What steps should we take to minimize risk during deployments? Parallel deployments? DB backups? Is there a specific time frame we should target or avoid?
Environment Configuration Changes
What environment variable, secrets.env, or appsettings.json changes need to be made?
Rollback Plan
In the event that we need to undo these changes in a production environment, what will it take?
External Dependencies
Do we need to coordinate with any third-party services or libraries (e.g. Microsoft Auth, USPS Address Validation, payment processors)? Are there API limits, contracts, or SLAs we need to consider?
Other Considerations
This includes miscellaneous other needs, like an update to github actions (which could also be under external dependencies) or a dependency on the customer having access to the Aderant API.
Sample Work Plan
### UI Changes Needed
We'll have to create an entirely new screen for ordering and checkout. We should also have the menu available.
#### User Focused Tests to Write
- What happens if the user's payment is declined?
- What happens if the user tries to buy an empty cart?
- What happens if the user tries to ship to a bad address?
- What happens if the user has multiple tabs opened?
- What happens if the user has had a tab open for seven months and items ordered are no longer available?
- Can users cancel their order?
### API Changes Needed
We need a menu endpoint and an order endpoint. We may also need a cancel order endpoint. These endpoints should be backed by handlers, data access classes, and repository classes.
We will also need a service to communicate with Stripe.
#### API Test Coverage
We need serverside enforcement of the user focused tests.
### Database Changes
We need to add tables to track:
- Available menu items
- How much of each ice cream is in stock.
- The current discounts/sales
- A historical record of orders that reflects prices and totals at time of purchase.
We need a field on the users table to indicate which users are allowed to order ice cream.
#### Data Preparation
By default, any user with the `COMP_ADMIN` role should be allowed to order ice cream.
### Blast Radius
The blast radius of this is rather small. It's an entirely new feature of Partner Portal that can be turned on or off without impacting the rest of the application.
#### What fragile / mission critical component are affected?
Only the Users table, but the change is adding a field so it's unlikely to have any impact on existing operations.
#### How dangerous are these changes?
Light
### Deployment
We need to make sure the customer has sufficient ice cream on hand to cover orders.
#### Environment Configuration Changes
#### Rollback Plan
We toggle the feature off and try and keep the ice cream frozen until we can either reinstate the feature or sell off the ice cream through other avenues (or return it).
### External Dependencies
We need to coordinate with Stripe as a payment processor.
### Other Considerations
This work has not been approved yet, so this work plan is conditional upon getting HK's approval to add ice cream sales to Partner Portal.