Add a row background color-coding legend to the top of the various core Trac reports

[pbiron]

The various Core Trac reports set specific background colors on some rows, but not others. And different reports use different background colors.

It would be great if there were a legend that explained the color-coding at the top of the report.

See this thread during ​today's New Contributor Meeting in slack for background (pun intended)

[dd32]

For some background for others, the colouring is very.. hidden and not understood by many, including those of us who use trac every day - Instead I infer it from the rows displayed directly..

You can return 1..5 as the __color__ field from a SQL report and that affects the row colours, by default I think it uses the priority field for that unless otherwise specified.

I believe "no colour" is 3 IIRC (edit: Looking at the below SQL, I'm guessing 0 is no colour, and 1-5 or 1-4 are various colours)

It ​looks like we can customise the background colours by returning a __style__ field.

To take ​https://core.trac.wordpress.org/tickets/major as an example..

  CASE
  WHEN priority = 'highest omg bbq' OR severity IN ( 'critical', 'blocker' )
  THEN 1
  WHEN priority = 'high' OR severity = 'major'
  THEN 2
  WHEN priority IN ( 'low', 'lowest' ) OR severity IN ( 'trivial', 'minor' )
  THEN 4
  ELSE 0
  END AS __color__,

But ​https://core.trac.wordpress.org/tickets/minor has:

  CASE
  WHEN keywords LIKE '%needs_unit_tests%' OR keywords LIKE '%needs_docs%'
  THEN 3
  WHEN keywords LIKE '%close%' OR keywords LIKE '%needs_review%'
    OR keywords LIKE '%dev_feedback%' OR keywords LIKE '%2nd_opinion%'
  THEN 2
  WHEN keywords LIKE '%reporter_feedback%'
  THEN 3
  WHEN keywords LIKE '%commit%'
  THEN 1
  WHEN keywords LIKE '%early%'
  THEN 2
  ELSE 3
  END as __color__,

[pbiron]

color-legend.png​ is kind of what I'm hoping to see at the top of the report, where ABC, DEF would be the explanation of what the colors mean (i.e., what is implied by the CASE STATEMENT in the query.

[dd32]

@pbiron You should (if you didn't before, you do now) have access to all the report editing features to take a closer look. Someone from the core team will need to ​go through each report (that lists all reports) and make a call on if the colours make sense, and if so, update the description of the reports. This is more a team-specific thing rather than a meta-task.

If you can find someone who is willing to do it (if not yourself) I can get them report edit access. As most of these reports are SQL based, it's easy to screw up a report to the point it refuses to render and no longer display the edit button (you have to manually craft the edit link in those cases). There's no history of edits either, so taking a backup (to a local text editor) of the SQL before it's touched is good practice.

The report description supports Trac Wiki formatting, so you can do tables, and other things like this: #fdc in background. ( [[span(style=background: #fdc, #fdc in background.)]])

[pbiron]

Here's a couple of examples of what the legend might look like for the "Next Major Release" report, using different types of wiki formatting.

First example is with the || table wiki-markup and the [[span(style=background-color: xxx)]] macro. Using the span macro I can't seem to get the background-color to cover the entire table cell. Also, the "caption" is an <h2> because I can't figure out how to add a "true" table <caption> with the wiki-markup.

Row background-color Legend

priority is 'highest omg bbq' or severity is 'critical' or 'blocker'

priority is 'highest omg bbq' or severity is 'critical' or 'blocker'

priority is 'high' or severity is 'major'

priority is 'high' or severity is 'major'

priority is 'low' or 'lowest' or severity is 'trivial' or 'minor'

priority is 'low' or 'lowest' or severity is 'trivial' or 'minor'

Second example is with the #!html processor syntax (i.e., embed a real html table). Personally, I like this version better:

• the background-color spans the whole table cell
• uses a "real" <caption> element in the table
• when added to the report header, it should be able to pick up the background-colors directly from the report.css stylesheet (in this comment I've done it with <tr style='xxx'>, since the report.css stylesheet isn't loaded here

Row background-color Legend

priority is 'highest omg bbq' or severity is 'critical' or 'blocker'

priority is 'highest omg bbq' or severity is 'critical' or 'blocker'

priority is 'high' or severity is 'major'

priority is 'high' or severity is 'major'

priority is 'low' or 'lowest' or severity is 'trivial' or 'minor'

priority is 'low' or 'lowest' or severity is 'trivial' or 'minor'

[dd32]

Second example is with the #!html processor syntax
...
when added to the report header, it should be able to pick up the background-colors directly from the report.css

That's what I would go with, I once again, forgot that the HTML processor was an option, and the ability to re-use the CSS stylesheets rather than rolling your own makes total sense.

[pbiron]

Just a test, I went ahead and added a legend to the ​Next Major Release report.

I think it looks pretty good. In addition to the markup in my previous comment, I bolded the variables and italicized the values in each row...to make then stand out more.

Let me know what you think.

[costdev]

@pbiron I've tried a few variations on the design - none of them are worth posting as they just don't work for readability.

IMHO, the one you've added to the report is easy to understand and, as a bonus, relatively straightforward to implement compared to other solutions that modify or extend styles to target th or td elements.

[pbiron]

thanx.
Another idea I had would be something like:

Row background-color Legend

Priority	Severity
highest omg bbq	critical or blocker
highest omg bbq	critical or blocker
high	major
high	major
low or lowest	trivial or minor
low or lowest	trivial or minor

[dd32]

I like it!

Another idea I had would be something like:

One thing that that doesn't make clear, is that it's an OR between the columns, and not an AND.

There are some reports where the highlighting is workflow based rather than priority/severity (eg ​https://core.trac.wordpress.org/tickets/minor), so in a way the verbose rows gives a consistent UI over all reports.

[pbiron]

Replying to dd32:

I like it!

Another idea I had would be something like:

One thing that that doesn't make clear, is that it's an OR between the columns, and not an AND.

I think if we were to go with that latest idea, there would have to be a sentence above or below the legend saying that it's OR of those 2 columns.

There are some reports where the highlighting is workflow based rather than priority/severity (eg ​https://core.trac.wordpress.org/tickets/minor), so in a way the verbose rows gives a consistent UI over all reports.

Yeah, I think most of the other reports are based on the workflow keywords, and in those other reports there are sometimes 5 or 6 different keywords that can cause a given color to be used.

I don't have strong feelings one way or the other about which way would be best...just throwing out ideas to see what sticks :-)

I ping'd Sergey in slack and asked him for ideas.