Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[docs] updated documentation to include references to v3 services #4763

Merged

Conversation

zenmonkeykstop
Copy link
Contributor

Status

Ready for review

Description of Changes

Fixes #4632 .

Adds upgrade documentation for v3 onion services.
Updates installation and onboarding documentation to refer to v3 services
Updates development documentation to refer to v3 services.

Note: The documentation for the instance restore and workstation rebuild process has not been addressed in this PR, as it's unclear to me how they will work under v3. More investigation required. Notes have been added to those docs temporarily, to let admins know that they're not applicable to instances running v3 services.

Testing

Docs-only PR:

  • review for clarity and correctness
  • follow installation and instance test instructions to verify that they're correct.
  • follow migration instructions to verify that servers are correctly updated to use v3
  • follow admin and journalist workstation update instructions to verify that they are also cut over correctly to v3.

Checklist

If you made non-trivial code changes:

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

If you made changes to documentation:

  • Doc linting (make docs-lint) passed locally

@zenmonkeykstop zenmonkeykstop changed the title updated documenation to include references to v3 services [docs] updated documentation to include references to v3 services Sep 6, 2019
@zenmonkeykstop zenmonkeykstop added this to the 1.0.0 milestone Sep 6, 2019
@eloquence eloquence added the docs label Sep 6, 2019
Copy link
Member

@eloquence eloquence left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for taking this one on @zenmonkeykstop! Just a first round of comments based on visual review only.

docs/v3_services.rst Outdated Show resolved Hide resolved
docs/v3_services.rst Outdated Show resolved Hide resolved
docs/v3_services.rst Outdated Show resolved Hide resolved
docs/v3_services.rst Outdated Show resolved Hide resolved
docs/v3_services.rst Outdated Show resolved Hide resolved
docs/v3_services.rst Outdated Show resolved Hide resolved
docs/v3_services.rst Show resolved Hide resolved
docs/v3_services.rst Outdated Show resolved Hide resolved
Copy link
Contributor

@redshiftzero redshiftzero left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

these docs look great, just a few comments inline

docs/install.rst Outdated Show resolved Hide resolved
docs/onboarding.rst Outdated Show resolved Hide resolved
docs/v3_services.rst Outdated Show resolved Hide resolved
docs/v3_services.rst Outdated Show resolved Hide resolved
Copy link
Contributor

@rocodes rocodes left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. My only comment is that people who are not familiar with onion services (for example, a journalist trying to back up their Tails USB and encountering the term in the docs, or potentially an Admin taking over care of the instance from someone else) might not know what this means to them or if it matters. ("What's an onion service? How can I tell if mine is v2 or v3?"). The 'how can I tell' in v3_services is fairly clear, but the document definitely goes quickly into advanced territory.

This note aside, I'd say really clear and looking good.

docs/backup_and_restore.rst Show resolved Hide resolved
@zenmonkeykstop
Copy link
Contributor Author

@rocodes thanks, adding a bit more explanatory text re onion services.

Copy link
Contributor

@emkll emkll left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Went through a visual review of these docs, they look great. I left a couple of small comments inline, though shouldn't block merge.

Has anyone performed a functional review of the instructions as part of their review? Else, I will perform a functional review first thing tomorrow, but it nothing stands out based on this visual review.

docs/install.rst Show resolved Hide resolved
docs/v3_services.rst Outdated Show resolved Hide resolved
docs/v3_services.rst Outdated Show resolved Hide resolved
docs/v3_services.rst Outdated Show resolved Hide resolved
docs/v3_services.rst Outdated Show resolved Hide resolved
docs/v3_services.rst Outdated Show resolved Hide resolved
docs/onboarding.rst Outdated Show resolved Hide resolved
docs/onboarding.rst Show resolved Hide resolved
Copy link
Contributor

@kushaldas kushaldas left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A few small changes requested.

docs/v3_services.rst Outdated Show resolved Hide resolved
@zenmonkeykstop
Copy link
Contributor Author

Lemme know when it's good and I'll flatten this PR before merge.

Copy link
Contributor

@kushaldas kushaldas left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Issues resolved. Approved.

@conorsch conorsch merged commit 08cee4e into freedomofpress:develop Sep 16, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

Successfully merging this pull request may close these issues.

[v3 onion migration] add detailed documentation for administrators
7 participants