Document the upgrade flag in the Admin Workstation troubleshooting guide

[nathandyer]

Describe the change

Sometimes, when an update doesn't go according to plan, it's necessary to perform a manual update and clear the flag by running:

rm ~/Persistent/.securedrop/securedrop_update.flag

We document this in each individual upgrade guide, but it can be difficult to find if you don't know to look there. We should consider mentioning it in the Admin Workstation troubleshooting section.

[rkraeher]

Hi there, I am interested in helping with this issue as a first time contributor. After looking over the docs, I am wondering if this is the page you are referring to add the tip and command, if there is some problem with the normal updating process:

Under the Updates: Workstations section https://docs.securedrop.org/en/stable/admin/reference/responsibilities.html

[nathandyer]

Hello @rkraeher, welcome! :wave:

We're happy you're here and wanting to help contribute to the SecureDrop docs!

In this case, I don't believe documenting this change in the "Updates: Workstations" section from the "Responsibilities" article that you linked would be ideal, because this level of detail is a bit more specific than what we generally put in that article. The responsibilities article is meant to give an overview to someone that might be considering SecureDrop, and is wanting to get a feel for the kinds of tasks that they will need to handle as part of maintaining one. As for the specifics of how to do those tasks, we generally keep those in the other areas of the documentation.

For this, I think it would be most at home somewhere in the "Admin Guide: Maintenance" section of the docs. There's an article for "Troubleshooting Kernel Updates" there, but I don't want to add this to it, because it is probably best to keep the workstation update troubleshooting items separate from the server/kernel troubleshooting items.

What I might suggest is that there be a completely new article created, called something like "Troubleshooting Workstation Updates", where the instructions for clearing that flag could live.

Does that sound reasonable to you? Do you have any questions about how to go about starting that? Please don't hesitate to reach out with any questions, or anything at all we can do to help as you work through your first contribution!

I did want to be sure to mention you're welcome (and encouraged!) to chat with us on Gitter any time, or join us for our standups here - they take place Monday through Thursday at noon ET / 9am PT / 16:00 UTC.

Thank you!

[rkraeher]

Great, thanks for the welcome 😁 Alright sure that sounds like something I can help with. I'll have a closer look at the available info for editing the docs before I circle back or head to the gitter with any questions.

As for right now, it probably goes without saying but I don't know anything about this specific troubleshooting topic. Are you thinking that to start, we just create this new article and it only has this one case of manual flag removal? Building it out as an article - like other tips or common problems - is a separate, future issue. I'm just trying to clarify scope and expectations :)

[nathandyer]

Thanks @rkraeher, that's a great question! Yes, in this case I think it's fine to build it out as an article with only this one item (removing the flag, and then the steps for manually doing an update - essentially, it should be similar to a copy of this entire section, but generalized not refer to a specific version), and then we can build it out further in the future.

[rkraeher]

hey @nathandyer I have opened this PR #507. Any feedback you have would be appreciated :)

[nathandyer]

Thanks so much @rkraeher! This is excellent! I left a few notes about one (small) suggested change, but once that's in, I think this will be ready to merge!