JIRA Refactor
JIRA contains the entire project history, but as the project has matured our use of JIRA has not kept up. This page proposes some changes to the structure of our JIRA project, to capture more information, simplify the data entry and nudge people towards more complete and accurate data entry.
Removals
To simplify the maintenance of JIRA, it would help to remove any unnecessary concepts. Mostly these are concepts we do not use in practice, except very spottily (so as to make them useless).
Remove Issue Types
Firstly, we propose the removal of the Wish and Test ticket types.
Issue Type | Reason |
|---|---|
Wish | is a feature/improvement, and can be better communicated via priority/complexity details we will introduce below |
Test | is logically a component, and a non-specific one at that |
Remove Fields
Field | Reason | Migration |
|---|---|---|
Labels | See detailed discussion below | |
Reviewer | Replaced by Reviewers | Populate empty Reviewers fields with contents of Reviewer |
Environment | Use is very patchy, noisy, and seemingly of little value over a comment if the extra content is useful | Propose new multi-select 'Platform' field with curated option list, in detail below |
Reproduced In | Use is very patchy; seems to offer little practical value above 'Since Version' |
|
Docs Text | Unused |
|
Due Date | Unused |
|
Epic Link | Unused |
|
External Issue ID | Unused |
|
External Issue URL | Unused |
|
Flags | Unused |
|
Sprint | Unused |
|
Time Tracking | Unused |
|
Remove Labels
This field clearly provides some utility today, however this seems almost exclusively to be a hack around the inadequacies
of our current JIRA data model. It is a poor tool for this job, and extremely noisy - there are ~500 labels, of which 300
are used exactly once and only ~100 are used > 5 times. Many of these labels are duplicates of each other, with different
punctuation, spelling or verbiage.
We have analysed all labels with >= 5 usages, and made sure they can all be represented in the changes we propose to the
data model.
remap cassandra jira labels.csv
Modifying/Expanding Existing Fields
Priority, Complexity, Severity and Category
Presently, Priority encodes some ill-defined combination of the first three of these independent properties, making it
hard to draw strong conclusions about any of them. We propose introducing two new fields, and clarifying the Priority
terminology to only suggest urgency, as well as reducing the number of priorities, since we don't effectively use them.
Priority
New Priority | Logically Replaces | Migrate From | Details |
|---|---|---|---|
Wish | Wish Issue Type | Wish Issue Type |
|
Low | Low-Minor | Low-Minor |
|
Normal | Minor-Major | Major | It wasn't clear what Minor or Major meant, but priority is a relative concept - a 'normal' is our logical baseline, and the default for a new issue |
High | Rest of Major |
| For tickets that community members plan to prioritise over other outstanding work, but has no immediate urgency |
Urgent | Critical-Blocker | Critical-Blocker | There's limited logical distinction between Critical and Blocker; it seems to make more sense to have a single 'do ASAP' tag |
Complexity
This field will be required, discussed further in the Workflow section below.
Complexity | Description | Initial Value |
|---|---|---|
Low Hanging Fruit | Trivial, No Dependencies, Localised, Accessible to New Contributors | Old Priority = Trivial or label=lhf |
Normal | Unremarkable; default |
|
Challenging | Localised, but requiring sophisticated analysis to understand |
|
Byzantine | Affecting many components, requiring sophisticated analysis to understand |
|
Impossible | Suspect this is not even possible (may be paired with Wish) |
|
Severity
This field will be required, discussed further in the Workflow section below. It will be available only for the Bug issue type.
Severity | Old Priorities | Description |
|---|---|---|
Low | Trivial-Low | Limited usability or low visibility impact with no impact on correctness; no urgency to resolve |
Normal | Minor-Major | This issue is either unremarkable or extraordinarily rare |
Critical | Critical-Urgent | This bug may have significant impact on correctness, availability, stability or some other critical production behaviour |
Discovered By
This field will be required for the Bug issue type. It will be used for analysis of our efforts to establish project quality.
- User Report
- Code Inspection
- New unit/dtest
- Performance Regression Testing
- Fuzz Testing
- Workload Replay Testing (e.g. FQL)
- Shadow Traffic Cluster
- Adhoc Testing
Bug Category
Required. Only provided as an option for the Bug issue type. Uses a Cascading Select List.
Category | Subcategory | Description |
|---|---|---|
Correctness | Persistent Corruption / Loss | Corruption that persists, and may propagate across the cluster |
| Response Corruption / Loss | Corruption that does not propagate or persist, only results in a client receiving erroneous responses |
| Semantic Failure | The logical behaviour is either not to spec, or the spec is faulty/ambiguous |
| Consistency Failure | Apparently successful action, but with lower consistency than required |
| Test Failure | A test is broken - if this turns out to be a legitimate bug, it should transition to the bug's category once diagnosed |
Availability | Response Crash | An operation does not succeed/respond because of a crash while servicing it, without affecting process stability |
| Process Crash | An isolated exceptional state occurs that brings down the affected node |
| Cluster Crash | A correlated exceptional state occurs across the cluster, bringing down a multiplicity of nodes |
| Unavailable | Apparently unavailable, when should be available |
Degradation | Resource Management | Either a resource leak or overcommit |
| Slow Use Case | A specific use case with suboptimal characteristics that have not yet been accommodated |
| Performance Bug/Regression | Unintended performance behaviour, including e.g. exceptions stalling compactions |
| Other Exception | An exception is being thrown, that is not coinciding with another category of degradation |
Security | Information Leakage |
|
| Privilege Escalation |
|
| Denial of Service |
|
Category
Required. Only provided as an option for the Feature and Improvement issue types.
Category | Description |
|---|---|
Performance | |
Change Semantics | Introduce new, or clarify/modify existing database semantic behaviours |
Improve Operability | Reduce the burden of operating a cluster (i.e. handle uncommon states better, with less operator involvement) |
Quality Assurance | Work to improve the guarantees we can make about the stability and correctness of Cassandra |
Component
Presently, the meaning of each component is unclear, even to long-serving project members. As such, it is very inconsistently
used and probably of limited value for analysis. We propose a more granular definition of components that more closely
matches the every day project vernacular.
There are two possible approaches, either using a Cascading Select List or a multi-select list, each with a tradeoff.
The former does not permit multiple selections, but the latter produces a lengthier list - however auto-completion should
make it manageable.
The biggest difficulty here will be migration. It might be that a "Legacy" component is the best option, with the old
scheme replicated exactly. We can then manually migrate tickets as the value presents itself, or organise such a transition.
This question in particular should be put to a discussion on the dev list before being put to a vote.
Cascading Select List Variant
Category | Subcategory |
|---|---|
Consistency | Coordination |
| Hints |
| Repair |
| Streaming |
| Bootstrap and Decommission |
| Batch Log |
Cluster Metadata | Ring Membership |
| Gossip |
| Schema |
Local Read/Write | Commit Log |
| Memtable |
| SSTable |
| Caching |
Compaction | General |
| DTCS |
| TWCS |
| LCS |
| STCS |
Config, Startup and Shutdown | Config |
| Startup |
| Shutdown |
| Launch Scripts |
Messaging | Internode |
| native v4 |
| native v5 |
| Thrift |
CQL | Syntax |
| Interpreter |
| UDF |
| UDA |
| UDT |
Observability | JMX |
| Metrics |
| Tracing |
| Logging |
Tools | fql |
| cqlsh |
| nodetool |
| sstable tools (upgrade, verify, etc) |
| bulk load |
| stress |
Testing | dtest |
| unit test |
| fuzz test |
| benchmark |
Documentation | Javadoc |
| Website |
| Blog Post |
Dependencies, Packaging and Build | Dependencies |
| Packaging |
| Build |
Multi-select List Variant
Consistency/Coordination
Consistency/Hints
Consistency/Repair
Consistency/Streaming
Consistency/Bootstrap and Decommission
Consistency/Batch Log
Cluster/Membership
Cluster/Gossip
Cluster/Schema
Local/Commit Log
Local/Memtable
Local/SSTable
Local/Caching
Local/Compaction
Local/Compaction/DTCS
Local/Compaction/TWCS
Local/Compaction/LCS
Local/Compaction/STCS
Local/Config
Local/Startup
Local/Shutdown
Local/Scripts
Messaging/Internode
Messaging/Native v4
Messaging/Native v5
Messaging/Thrift
CQL/Syntax
CQL/Interpreter
CQL/UDF
CQL/UDA
CQL/UDT
Observability/JMX
Observability/Metrics
Observability/Tracing
Observability/Logging
Tools/fql
Tools/cqlsh
Tools/nodetool
Tools/sstable
Tools/bulk load
Tools/stress
Tests/dtest
Tests/unit
Tests/fuzz
Tests/benchmark
Docs/Javadoc
Docs/Website
Docs/Blog
Packaging
Dependencies
Build
Feature
Features tend to cut across many components of the database. So an orthogonal field to track these, instead of ill-defined
labels is probably of utility. It is any way useful to track things like bugs per component/feature combination.
This field will not be required, since many tickets will not touch on features explicitly.
- Lightweight Transactions
- Counters
- Change Data Capture
- Transient Replication
- 2i Index
- SASI
- Materialized Views
- Virtual Nodes
- Virtual Tables
- Authorization
- Encryption
- Compression
- KMS/Vault
- Super Columns
Other New Fields
Platform
To replace the existing Environment field that is of limited value.
A curated list, that can only be modified by project members. Initially seeded with:
- Java {7,8,9,10,11}
- OpenJDK, Oracle Java, Azul, ...
- Linux (major kernel versions), Windows, OpenBSD, ...
- x86, ... (added as necessary)
Impacts
To replace certain labels, and help external maintainers track features of relevance to them.
A curated list, that can only be modified by project members. Initially seeded with:
- Clients
- Docs
- Security
- JDBC
- Spark
- Hadoop
Test and Documentation Plan
A new required field containing free-form text field, required when transitioning to 'In Progress'.
The intended purpose is to encourage explicit upfront consideration of the work needed on these areas
either before or following commit. This may entail filing follow-up tickets that need to be resolved before release,
or a brief statement on the tests that will be written, or simply 'n/a'.
This also provides a promise to hold implementors to before release, and a point of discussion before a ticket lands.
Workflow
To encourage high quality data entry and better observability, we propose a few changes to the project Workflow.
New Triage State
Currently it is easy for the project to miss a ticket, and for that ticket to fall through the cracks indefinitely.
At the same time, user reports cannot be expected to fill out all of the required fields accurately.
It's proposed that we introduce a new initial state named 'Triage' that has no required fields, and that anybody may file.
To transition to the Open state, you must be a committer in JIRA (or, perhaps, we can introduce a new role for those
on the way to committership), and must ensure the required fields have been correctly filled out before doing so.
New Workflow
Triage <-> (Awaiting Feedback) -> Open/Reopened -> In Progress -> Patch Available -> Review in Progress -> Ready to Commit -> Resolved
Obviously, the actual transition graph is much more complex than this.
Required fields on transition to 'Open'
- Component
- Priority
- Complexity
- Bug/Change Category
- Severity (if bug)
- Discovered By (if bug)
Required fields on transition to 'Ready for Review'
- Impacts
- Test and Documentation Plan
Required fields on transition to 'Committed'
- Reviewers
- Since Version (if bug)
- Fix Versions
Field Display Order
- Project
- Issue Type
- Summary
- Bug/Change Category
- Discovered By
- Component
- Priority
- Complexity
- Impacts
- Description
- Since Version
- Assignee
- Reviewers
- Test and Documentation Plan
- Tester
- Reporter