Updates v3 warnings with varying messages based on instance configs #5679

zenmonkeykstop · 2020-12-21T16:45:31Z

Status

Work in progress

Description of Changes

Fixes #5672 .

Updates the upgrade banner text/color in the Journalist Interface for instances with v2+v3 onion services enabled, and separate more urgent message if an instance is v2-only.

Testing

Staging:

run make build-debs and make staging against this branch
navigate to the JI login page and verify that no banner is displayed
log in to the JI and verify that the v2+v3 banner is displayed
log out of the JI
log in to the app-staging server, remove the file /var/lib/securedrop/source_v3_url, and restart apache
navigate to the JI login page and verify that no banner is displayed
log in to the JI and verify that the v2-only banner is displayed

Deployment

Deployed as part of regular install/update.

Checklist

If you made changes to the server application code:

Linting (make lint) and tests (make test) pass in the development container

If you made non-trivial code changes:

I have written a test plan and validated it for this PR

Choose one of the following:

I have opened a PR in the docs repo for these changes, or will do so later
I would appreciate help with the documentation
These changes do not require documentation

zenmonkeykstop · 2020-12-21T17:15:18Z

I'm leaving this as draft for now pending UX feedback. For @eloquence and/or @ninavizz attention, screenshots attached with suggested text/color from #5672 for both cases (and one with a smaller window just coz):

codecov-io · 2020-12-21T22:24:16Z

Codecov Report

Merging #5679 (ed2a20e) into develop (0454478) will decrease coverage by 4.11%.
The diff coverage is 100.00%.

@@             Coverage Diff             @@
##           develop    #5679      +/-   ##
===========================================
- Coverage    85.54%   81.43%   -4.12%     
===========================================
  Files           52       53       +1     
  Lines         3771     3969     +198     
  Branches       474      497      +23     
===========================================
+ Hits          3226     3232       +6     
- Misses         440      632     +192     
  Partials       105      105

Impacted Files	Coverage Δ
securedrop/journalist_app/__init__.py	`93.69% <100.00%> (+0.23%)`	⬆️
securedrop/loaddata.py	`0.00% <0.00%> (ø)`
securedrop/source_app/utils.py	`92.20% <0.00%> (+2.59%)`	⬆️

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 0454478...ed2a20e. Read the comment docs.

emkll · 2021-01-05T15:03:44Z

securedrop/journalist_templates/base.html

-      <div id="v2-onion-eol" class="warning-banner">
-        {{ gettext('<strong>Update Required:</strong> Your SecureDrop servers are still running v2 onion services, which are being phased out for security reasons. In February 2021, v2 onion services will be disabled, and your SecureDrop servers may become unreachable. <a href="//securedrop.org/v2-onion-eol" rel="noreferrer">Learn More</a>') }}
+      <div id="v2-onion-eol" class="alert-banner">
+        {{ gettext('<strong>Update Required:</strong> You must switch your SecureDrop to v3 onion services to ensure that it is reachable after April 30, 2021. <a href="//securedrop.org/v2-onion-eol" rel="noreferrer">Learn More</a>') }}


What about "update required" -> "action required"?

https://www.youtube.com/watch?v=ussCHoQttyQ

That might have been a bit facetious - I think it would be good to hash out final wording with the larger group and with @ninavizz' input.

emkll

Thanks for the changes @zenmonkeykstop , once tests are added I believe this should be good to merge. My comments are mostly related to the language/style of the alerts, best suited to discuss in a synchronous discussion to reduce back and forth

emkll · 2021-01-05T15:09:18Z

securedrop/journalist_templates/base.html

+
+      {% if g.show_v2_onion_migration_warning %}
+      <div id="v2-onion-eol" class="alert-banner">
+        {{ gettext('<strong>Update Required:</strong> Your SecureDrop servers are still reachable via v2 and v3 onion services. Make sure admins, journalists, and sources are using v3 onion services - then disable v2 onion services. <a href="//securedrop.org/v2-onion-eol" rel="noreferrer">Learn More</a>') }}


I propose we word it as follows, as I was under the impression we were will be disabling v2 services as part of 1.8.0 (or later):
Make sure admins, journalists and sources are using v3 onion services, as they will be disabled disabled on $DATE

emkll · 2021-01-05T15:09:54Z

securedrop/journalist_templates/base.html

+      </div>
+      {% endif %}
+
+      {% if g.show_v2_onion_migration_warning %}


Given that v3 has already been configured, it might make sense to make this alert a lower level than alert

securedrop/sass/modules/_alert-banner.sass

ninavizz · 2021-01-05T19:03:12Z

Just created tickets in the docs repo, for requested changes for the Docs page this banner lands upon. Important for the banner to be meaningful or have impact, as it's the behavior of users from an experience we care about; not page prettiness.
freedomofpress/securedrop-docs#122

Will post mox here for banner, later today.

ninavizz · 2021-01-06T08:39:27Z

Found the Issue for this, so put UX stuff in it per 2019 discussion to keep UX discussion out of PRs.
#5672

eloquence · 2021-01-07T00:05:00Z

securedrop/journalist_templates/base.html

+
+      {% if g.show_v2_onion_migration_warning %}
+      <div id="v2-complete-migration" class="alert-banner">
+        <img src="{{ url_for('static', filename='i/bang-circle.png') }}" width="20" height="20"> {{ gettext('<strong>Update Required:</strong> Steps remain to complete your onion service update. Please notifyyour admin. <a href="//securedrop.org/v2-onion-eol" rel="noreferrer">Learn More</a>') }}


typo: notifyyour->notify your

I'm fine with the wording here but I would suggest a slightly tweaked version

Update Completion Required: Steps remain to complete your SecureDrop server's update to v3 onion services.

Rationale:

The wording "Update Completion" is from @ninavizz's proposal in Add clearer action reminder in Journalist Interface to enable v3 #5672 and I think makes sense, especially since completing the update may involve landing page changes & multi-stakeholder comms. If it sounds too nonstandard, perhaps "Action Required" would work as well.

I think the phrase "v3 onion services" should be included because it very clearly identifies the technical component we're talking about (if I'm an admin, there's at least a chance I've heard of it). The user shouldn't have to click through to "Learn more" to find out that important detail.

IMO we can ditch the "Please notify" for brevity; it's essentially implied, not included in the other notice, and the person seeing the notice may well be an admin.

How about best of all worlds:
"Action Required Set up v3 onion services before April 30 to keep your SecureDrop servers online. Learn more"
"Action Required Complete the v3 onion services setup before April 30. Learn more"

(This suggestion is based on both your comments above and feedback in #5672 - it's about as terse as I think it can get while still being accurate. I'm dead set against "Update Completion Required," it has a high cognitive load factor compared to just "Update required" IMO and reads like an awkward phishing attempt.)

ninavizz · 2021-01-07T17:28:58Z

Clearly identifying technical components to non-technical users, I am not ok with. This is not the time nor the place for that. Docs text is the time and place for that. Likewise, "implying" what action we want the user to take in a notification breaks the number one rule of notifications, which is to respect your user enough to directly tell them what is being asked of them.

This text is for journalist users. Not admins. Sure, "some" admins are both, but the primary user here is journalists—whom are non-technical users. Period. We need them to alert their admins. Behavioral compliance is the desired outcome. My recommendations follow that. It is a known problem, getting orgs to follow update instruction. Please try something new, here, for a change.

Most of the edit suggestions from @eloquence and @zenmonkeykstop break best-practice rules for messaging text, which frustrates me a lot. I did not compose the text willy-nilly, and am not looking for excuses to justify poor grammar. Those are simply industry standard rules, period. Security engineers are not the audience; non-technical users, are.

The best summation of best practice "rules" for UI text that I've seen to date, are in Material.io's guide. I cannot give my blessing to messaging that neither tells the user explicitly what to do, nor that includes overly technical details. If this were the Admin UI, it would be different, but it is not. It is the Journalist UI.

zenmonkeykstop · 2021-01-07T17:40:38Z

Fair enough, will update banners as per text in #5672 and call it done.

eloquence · 2021-01-07T17:44:03Z

Clearly identifying technical components to non-technical users, I am not ok with.

If this is in reference to whether or not to include "v3 onion services" in the banner, then I disagree, but I'll defer to @emkll to make the final call here in review.

emkll

I left a few comments inline, but tl;dr I think that the language proposed in #5679 (comment) seems like the best approach to me.

I however disagree with the following:

IMO we can ditch the "Please notify" for brevity; it's essentially implied, not included in the other notice, and the person seeing the notice may well be an admin.

It seems that through the back-and-forth and different perspectives, we all agree with the ultimate goal of this change: Upon seeing the notification,a Journalist should contact their administrator (so that the administrator can migrate their instance to v3 onion services). This will ensure journalists reach out to admins, reducing the risk of potential confusion. We should therefore be concise and accurate when describing the issue.

In other words, the goal of this PR as I see it, is to

Have journalists contact admins
When contacting their admin, the journalist can describe the issue in less than a sentence

Better phrased by @zenmonkeykstop in #5672 (comment) :

We're not providing directly relevant instructions/warnings, we're trying to convince users that there's a completely new problem that they have to go and solve somewhere else.

The guidance/instructions for the migration (and its rationale) is provided in the documentation, this PR merely introduced a notification. Being concise and (technically) accurate to me is key here, provided of course, it results in a journalist reaching out to an administrator after looking at the notification.

We should ensure both journalists and admins are not alarmed by the messaging (adhering to the existing tone/language in the Journalist Interface is one way of doing that). Given the timeline, I would be inclined to reserve changes to style for a later date, especially given the relatively straightforward nature of the task, from the perspective of a journalist (please reach out to your admin)

What do you all think with the following?
"Action Required Set up v3 Onion services before April 30 to keep your SecureDrop servers online. Please contact your administrator or learn more"
"Action Required Complete the v3 Onion Services setup before April 30. Please contact your administrator or learn more"

emkll · 2021-01-07T18:50:45Z

securedrop/journalist_templates/base.html

+
+      {% if g.show_v2_onion_migration_warning %}
+      <div id="v2-complete-migration" class="alert-banner">
+        <img src="{{ url_for('static', filename='i/bang-circle.png') }}" width="20" height="20"> {{ gettext('<strong>Update Required</strong>&nbsp;&nbsp;Steps remain to complete your onion service update. Please notify admin. <a href="//securedrop.org/v2-onion-eol" rel="noreferrer">Learn More</a>') }}


I agree with your comment in #5679 (comment)

steps remain to complete -> complete , in the spirit of not only less is more, but it may be interpreted by a journalist that they (the journalist) need to update something.

I propose we also update the wording
please notify admin -> please notify your administrator.

From the associated issue:

UI text is often not grammatically correct per-se, for usability reasons.

In my experience, this makes translation more difficult.

emkll · 2021-01-07T19:06:07Z

securedrop/journalist_templates/base.html

-      <div id="v2-onion-eol" class="warning-banner">
-        {{ gettext('<strong>Update Required:</strong> Your SecureDrop servers are still running v2 onion services, which are being phased out for security reasons. In February 2021, v2 onion services will be disabled, and your SecureDrop servers may become unreachable. <a href="//securedrop.org/v2-onion-eol" rel="noreferrer">Learn More</a>') }}
+      <div id="v2-onion-eol" class="alert-banner">
+        <img src="{{ url_for('static', filename='i/bang-circle.png') }}" width="20" height="20"> {{ gettext('<strong>Update Required</strong>&nbsp;&nbsp;Your SecureDrop servers must be updated to v3 onion services by April 30 to remain live. <a href="//securedrop.org/v2-onion-eol" rel="noreferrer">Learn More</a>') }}


I recommend something along the lines of "please notify your administrator" per @ninavizz comment in #5679 (comment)

We need them to alert their admins.

emkll · 2021-01-07T19:17:23Z

securedrop/journalist_templates/base.html

-      <div id="v2-onion-eol" class="warning-banner">
-        {{ gettext('<strong>Update Required:</strong> Your SecureDrop servers are still running v2 onion services, which are being phased out for security reasons. In February 2021, v2 onion services will be disabled, and your SecureDrop servers may become unreachable. <a href="//securedrop.org/v2-onion-eol" rel="noreferrer">Learn More</a>') }}
+      <div id="v2-onion-eol" class="alert-banner">
+        <img src="{{ url_for('static', filename='i/bang-circle.png') }}" width="20" height="20"> {{ gettext('<strong>Update Required</strong>&nbsp;&nbsp;Your SecureDrop servers must be updated to v3 onion services by April 30 to remain live. <a href="//securedrop.org/v2-onion-eol" rel="noreferrer">Learn More</a>') }}


nit: I think onion services need to be capitalized

emkll · 2021-01-07T20:04:27Z

securedrop/journalist_templates/base.html

-      <div id="v2-onion-eol" class="warning-banner">
-        {{ gettext('<strong>Update Required:</strong> Your SecureDrop servers are still running v2 onion services, which are being phased out for security reasons. In February 2021, v2 onion services will be disabled, and your SecureDrop servers may become unreachable. <a href="//securedrop.org/v2-onion-eol" rel="noreferrer">Learn More</a>') }}
+      <div id="v2-onion-eol" class="alert-banner">
+        <img src="{{ url_for('static', filename='i/bang-circle.png') }}" width="20" height="20"> {{ gettext('<strong>Update Required</strong>&nbsp;&nbsp;Your SecureDrop servers must be updated to v3 onion services by April 30 to remain live. <a href="//securedrop.org/v2-onion-eol" rel="noreferrer">Learn More</a>') }}


should we include the year?

eloquence · 2021-01-07T20:40:18Z

What do you all think with the following?

Sounds good from my end (I'm assuming formatting as in the current implementation). I have a soft preference for "Please contact your administrator. [Learn more]" over "Please contact your administrator or learn more", but either is fine with me. Thanks much y'all for hammering this out.

zenmonkeykstop · 2021-01-07T20:49:02Z

Updating banner text based on recent discussion.

emkll

Thanks @zenmonkeykstop and everyone for input here, this is now good to merge for inclusion in the upcoming 1.7.0 release.

zenmonkeykstop force-pushed the 5672-update-v3-warnings branch from 30bcae8 to 34be75c Compare December 21, 2020 17:13

zenmonkeykstop added this to the 1.7.0 milestone Dec 21, 2020

zenmonkeykstop force-pushed the 5672-update-v3-warnings branch from 705d120 to 9b61677 Compare January 4, 2021 16:56

emkll self-requested a review January 5, 2021 14:42

emkll self-assigned this Jan 5, 2021

zenmonkeykstop marked this pull request as ready for review January 5, 2021 14:49

zenmonkeykstop requested review from kushaldas and redshiftzero as code owners January 5, 2021 14:49

emkll reviewed Jan 5, 2021

View reviewed changes

zenmonkeykstop added 2 commits January 5, 2021 16:50

updated v3 warnings with varying CTA based on instance configs

ad1e140

removed unnecessary test

2f4d8ce

zenmonkeykstop force-pushed the 5672-update-v3-warnings branch from 9b61677 to 2f4d8ce Compare January 5, 2021 21:56

Updated banner rendering, text based on UX review.

8f1d356

zenmonkeykstop requested a review from conorsch as a code owner January 6, 2021 15:44

zenmonkeykstop mentioned this pull request Jan 6, 2021

Add clearer action reminder in Journalist Interface to enable v3 #5672

Closed

eloquence reviewed Jan 7, 2021

View reviewed changes

further banner text updates

740994f

emkll reviewed Jan 7, 2021

View reviewed changes

Further banner text revisions

ed2a20e

emkll approved these changes Jan 8, 2021

View reviewed changes

emkll merged commit 7f16b5f into develop Jan 8, 2021

emkll deleted the 5672-update-v3-warnings branch January 8, 2021 18:14

zenmonkeykstop mentioned this pull request Jan 13, 2021

Reorders and extends the Admin guide freedomofpress/securedrop-docs#132

Merged

3 tasks

conorsch mentioned this pull request Jan 15, 2021

Release SecureDrop 1.7.0 #5689

Closed

22 tasks

eloquence mentioned this pull request Feb 2, 2021

Add EOL warning and disable Source Interface on instances running Ubuntu 16.04 after April 30 #5688

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Updates v3 warnings with varying messages based on instance configs #5679

Updates v3 warnings with varying messages based on instance configs #5679

zenmonkeykstop commented Dec 21, 2020 •

edited by emkll

Loading

zenmonkeykstop commented Dec 21, 2020 •

edited

Loading

codecov-io commented Dec 21, 2020 •

edited

Loading

emkll Jan 5, 2021

zenmonkeykstop Jan 5, 2021

zenmonkeykstop Jan 5, 2021

emkll left a comment

emkll Jan 5, 2021

emkll Jan 5, 2021

ninavizz commented Jan 5, 2021 •

edited

Loading

ninavizz commented Jan 6, 2021

eloquence Jan 7, 2021

zenmonkeykstop Jan 7, 2021 •

edited

Loading

ninavizz commented Jan 7, 2021 •

edited

Loading

zenmonkeykstop commented Jan 7, 2021

eloquence commented Jan 7, 2021

emkll left a comment

emkll Jan 7, 2021

emkll Jan 7, 2021

emkll Jan 7, 2021

emkll Jan 7, 2021

emkll Jan 7, 2021

eloquence commented Jan 7, 2021 •

edited

Loading

zenmonkeykstop commented Jan 7, 2021

emkll left a comment

Updates v3 warnings with varying messages based on instance configs #5679

Updates v3 warnings with varying messages based on instance configs #5679

Conversation

zenmonkeykstop commented Dec 21, 2020 • edited by emkll Loading

Status

Description of Changes

Testing

Staging:

Deployment

Checklist

If you made changes to the server application code:

If you made non-trivial code changes:

zenmonkeykstop commented Dec 21, 2020 • edited Loading

codecov-io commented Dec 21, 2020 • edited Loading

Codecov Report

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

emkll left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ninavizz commented Jan 5, 2021 • edited Loading

ninavizz commented Jan 6, 2021

Choose a reason for hiding this comment

zenmonkeykstop Jan 7, 2021 • edited Loading

Choose a reason for hiding this comment

ninavizz commented Jan 7, 2021 • edited Loading

zenmonkeykstop commented Jan 7, 2021

eloquence commented Jan 7, 2021

emkll left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

eloquence commented Jan 7, 2021 • edited Loading

zenmonkeykstop commented Jan 7, 2021

emkll left a comment

Choose a reason for hiding this comment

zenmonkeykstop commented Dec 21, 2020 •

edited by emkll

Loading

zenmonkeykstop commented Dec 21, 2020 •

edited

Loading

codecov-io commented Dec 21, 2020 •

edited

Loading

ninavizz commented Jan 5, 2021 •

edited

Loading

zenmonkeykstop Jan 7, 2021 •

edited

Loading

ninavizz commented Jan 7, 2021 •

edited

Loading

eloquence commented Jan 7, 2021 •

edited

Loading