[GitHub] [trafficcontrol] ocket8888 commented on a change in pull request #6398: Add clarity and emphasis to REFRESH REFETCH options

[GitBox <gi...@apache.org>]

ocket8888 commented on a change in pull request #6398:
URL: https://github.com/apache/trafficcontrol/pull/6398#discussion_r761550565



##########
File path: CHANGELOG.md
##########
@@ -44,6 +44,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/).
 - Changed Invalidation Jobs throughout (TO, TP, T3C, etc.) to account for the ability to do both REFRESH and REFETCH requests for resources.
 - The `admin` Role is now always guaranteed to exist, and can't be deleted or modified.
 - Updated `t3c-apply` to reduce mutable state in `TrafficOpsReq` struct.
+- Traffic Portal: Changed the warning text for creating a Content Invalidation job to add clarity and to emphasize severity. 

Review comment:
       This hasn't actually changed though, has it? I see the line 
   > - Changed Invalidation Jobs throughout (TO, TP, T3C, etc.) to account for the ability to do both REFRESH and REFETCH requests for resources.
   
   above, so that hasn't actually been released, thus the warning text is not now different in a new release than it has been before. You know what I'm trying to say? I feel like these are arcane cascading clauses and I'm getting lost in them.

##########
File path: traffic_portal/app/src/common/modules/form/deliveryServiceJob/form.deliveryServiceJob.tpl.html
##########
@@ -31,7 +31,12 @@
         <div class="helptext">
             <aside class="warning">
                 <h6>Warning</h6>
-                <p>Delivery service origin(s) must support IMS in order to safely invalidate content</p>
+                <p>REFRESH (preferred default) will mark the matching asset(s) as STALE and an IMS request of the asset(s) from the origin will be performed. Origins that fully adhere 
+                    to the <a href="https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.25">If-Modified-Since</a> 
+                    and <a href="https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.26">If-None-Match</a> specification can safely invalidate content using REFRESH.</p>
+                <p>REFETCH will mark the matching asset(s) as a cache MISS and a new full request of the asset(s) from the origin will be performed. 
+                    This operation is expensive and it is HIGHLY RECOMMENDED that the specified regex is very specific when using REFETCH.</p>

Review comment:
       This looks like a [description list](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl) to me

##########
File path: traffic_portal/app/src/common/modules/form/deliveryServiceJob/form.deliveryServiceJob.tpl.html
##########
@@ -31,7 +31,12 @@
         <div class="helptext">
             <aside class="warning">
                 <h6>Warning</h6>
-                <p>Delivery service origin(s) must support IMS in order to safely invalidate content</p>
+                <p>REFRESH (preferred default) will mark the matching asset(s) as STALE and an IMS request of the asset(s) from the origin will be performed. Origins that fully adhere 

Review comment:
       I don't think "stale" and "miss" are being used as initialisms here, why are they in all caps?

##########
File path: traffic_portal/app/src/common/modules/form/deliveryServiceJob/form.deliveryServiceJob.tpl.html
##########
@@ -31,7 +31,12 @@
         <div class="helptext">
             <aside class="warning">
                 <h6>Warning</h6>
-                <p>Delivery service origin(s) must support IMS in order to safely invalidate content</p>
+                <p>REFRESH (preferred default) will mark the matching asset(s) as STALE and an IMS request of the asset(s) from the origin will be performed. Origins that fully adhere 
+                    to the <a href="https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.25">If-Modified-Since</a> 
+                    and <a href="https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.26">If-None-Match</a> specification can safely invalidate content using REFRESH.</p>
+                <p>REFETCH will mark the matching asset(s) as a cache MISS and a new full request of the asset(s) from the origin will be performed. 
+                    This operation is expensive and it is HIGHLY RECOMMENDED that the specified regex is very specific when using REFETCH.</p>

Review comment:
       emphasis should use [the emphasis HTML element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/em), or to convey contextual urgency rather than literal verbal stress, use [the strong importance element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/em). All caps should not be used for either - and not just because there are better ways (and if you still want them in all caps that can be done accessibly through styling with `text-transform: uppercase` as a CSS rule) but because it causes accessibility problems. Screen-readers will read words in all caps letter-by-letter, which is why that should be reserved for cases where it's appropriate, like abbreviations, acronyms, and initialisms (which is why "IMS" is fine here). 




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@trafficcontrol.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org