JIRA Workflow Proposals

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. This will better allow us to measure release quality over time and identify when Cassandra is ready for (or due a) release.

Summary

• Removal of issues types: Wish and Test
• Fields
  • Removed: Labels, Reviewer, Environment, Reproduced In, Docs Text, Due Date, Epic Link, External Issue Id, External Issue URL, Flags, Sprint, Time Tracking
  • Modified: Priority, Component
  • Added: Complexity, Feature, Impacts, Test and Documentation Plan, Platform
  • Added (Bug only): Severity, Bug Category, Discovered By
  • Added (Improvement and Feature only): Change Category
• Workflow
  • New States: Triage, Review in Progress, Change Requested
  • Transitions with required fields
  • Order of field display changed
• Issue Permissions
  • Anybody may file a Triage ticket
  • Only contributors will be permitted to edit a ticket, and transition it further in the workflow
• Schema Permissions
  
  • Only committers will be permitted to introduce new options to the schema for the fields: Component, Feature, Platform.  Removals can be negotiated with the person who introduced them, or litigated on list.
  • All other fields should not have their schema-defined options modified without endorsement from the mailing list.

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.

Remove Fields

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

Complexity

This field will be required, discussed further in the Workflow section below.

Bug Only Fields

Severity

This field will be required, discussed further in the Workflow section below. It will be available only for the Bug issue type.

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.

/Bug Only Fields

Change Category

Required. This is the only field unique to the Feature and Improvement issue types.

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

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
 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
• UDF
• UDT
• UDA

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)
• NVMe, SSD, Magnetic HDDs
• AWS, GCE, Azure

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.  We propose:

1. Introducing some new issue states to better track the current ticket status, and handover between responsible parties;
2. Making certain fields required during certain state transitions, to ensure we have the minimally necessary ticket information complete at each stage'
3. Reordering the fields that we display on transition, to highlight the most important

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 contributor in JIRA (equivalent to able to assign tickets), and must ensure the required fields have been correctly filled out before doing so.

New 'Review in Progress' and 'Change Requested' States

Presently there is no way to indicate that a patch is under active review, so it is hard for assignees to monitor the progress of their patch to completion.  Similarly, there is no useful way for the reviewer to indicate that their comments are ready to be addressed by the assignee.  With the introduction of these two states, there is a clear handover at each stage of the process.  This makes it clear who is responsible for taking the patch forward to the next step, as well as transparency over progress on any steps you are waiting on.

Removal of Reopened State

The Reopened state is of dubious value - arguably, it is in any scenario more helpful to file a new ticket, link the two via a relation, and leave a comment on the original for interested parties to migrate to the new discussion.  In any case, its use is frowned upon and rare.  It will of course remain possible to move a ticket from the 'Resolved' state to e.g. the Open state, but this will not be officially sanctioned except when correcting filing/procedural errors.

New Workflow

The column on the right represents the states we will provide buttons for performing a simple transition between.  It does not include all acceptable transitions.

Required fields on transition to 'Open'

• Component
• Priority
• Complexity
• Bug/Change Category
• Severity (if bug)
• Discovered By (if bug)

Required fields on transition to 'Patch Available'

• Impacts
• Test and Documentation Plan

Required fields on transition to 'Review in Progress'

• Reviewers

Required fields on transition from 'Ready to Commit' to 'Resolved'

• 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