Clarify upgrade notes ahead of 1.4.0 release #6033

neilisfragile · 2019-09-13T10:03:31Z

Upgrade notes to explain changes in 1.4 brought about by privacy project

If you spot typos, things that are obviously wrong please just edit and commit direct.

Rendered

anoadragon453

A few changes, but very clear and easy to read :)

UPGRADE.rst

anoadragon453 · 2019-09-13T10:09:13Z

UPGRADE.rst

+In the medium term the vector.im and matrix.org Identity servers will disable
+sending email and SMS entirely, however in order to ease the transition they
+will retain the capability to send email and SMS for a limited period. Email
+will be disabled on XXX (giving 2 months notice), disabling SMS will follow


Mental note: Make sure this gets filled in.

UPGRADE.rst

Co-Authored-By: Andrew Morgan <[email protected]>

anoadragon453 · 2019-09-13T10:48:45Z

You can make batch updates from the Files tab btw

Co-Authored-By: Andrew Morgan <[email protected]>

richvdh · 2019-09-13T12:13:17Z

neil: please can you give the PR a better name?

UPGRADE.rst

anoadragon453 · 2019-09-17T10:36:47Z

We're going to need to include the fact that adding threepids to your account won't work until the homeserver figures out how it's handling email/msisdns. This won't prevent you from binding threepids to Identity Servers through your homeserver at the protocol level, but Riot won't give you the option to bind until a threepid has been added to your account.

anoadragon453 · 2019-09-18T13:51:19Z

Additionally, there are 4 more new email templates to worry about. add_threepid.html, add_threepid.txt, add_threepid_failure.html and add_threepid_success.html.

richvdh

I have a few suggestions, but I think we're going to need to iterate on this.
What steps should I expect to have to take if I downgrade to v1.3.1? (particularly if I was foolish enough not to keep a copy of my old homeserver.yaml)

UPGRADE.rst

Co-Authored-By: Richard van der Hoff <[email protected]> Co-Authored-By: Andrew Morgan <[email protected]>

…grade_notes

babolivier

Plus some lines aren't correctly wrapped at 80 char (or whichever value we should use).

UPGRADE.rst

changelog.d/6027.doc

Co-Authored-By: Richard van der Hoff <[email protected]>

…nto neilj/upgrade_notes

UPGRADE.rst

richvdh · 2019-09-24T14:37:04Z

UPGRADE.rst

+In the medium term the vector.im and matrix.org identity servers will disable
+sending email and SMS for homeservers entirely, however in order to ease the
+transition they will retain the capability to send email and SMS for a limited
+period. Email will be disabled on Monday 2nd December 2019 (giving roughly 2


this paragraph and the next still talk about stopping the ISes from sending email and sms altogether. I appreciate that you're trying to be brief for clarity but I worry that it's actively misleading - particularly given the repetition.

@richvdh I don't follow, is there some case where the IS sends an email on behalf of a homeserver that I am not thinking of? Or do I just need to make the fact I am talking about email and SMS on behalf of homeservers clearer?

the latter. There are cases when an IS sends an email independently, so "Email will be disabled" is incorrect.

maybe we should call it "support for delegated 3pid verification" or something, instead of "sending email"

Improve clarity Co-Authored-By: Richard van der Hoff <[email protected]>

…nto neilj/upgrade_notes

richvdh · 2019-09-25T12:31:38Z

UPGRADE.rst

+
+It is possible for a user to associate an email address or phone number
+with their account, for a number of reasons:
+ * for use when logging in, as an alternative to the user id.


there's a formatting fail here. I think it needs to lose the indentation

richvdh · 2019-09-25T12:33:03Z

UPGRADE.rst

+matrix.org.
+
+In Synapse 1.4.0, for security and privacy reasons, the homeserver will no
+longer delegate 3pid validation to an identity server by default and instead the


probably my bad, but we should decide if we are calling it 'verification' or 'validation'. I think 'verification'?

UPGRADE.rst

richvdh · 2019-09-25T12:35:03Z

UPGRADE.rst

+In the medium term the vector.im and matrix.org identity servers will disable
+sending email and SMS for homeservers entirely, however in order to ease the
+transition they will retain the capability to send email and SMS for a limited
+period. Email will be disabled on Monday 2nd December 2019 (giving roughly 2


maybe we should call it "support for delegated 3pid verification" or something, instead of "sending email"

UPGRADE.rst

anoadragon453 · 2019-09-25T12:56:11Z

UPGRADE.rst

+Following upgrade, to continue sending email (and therefore register via an
+email address) admins can either:-
+
+* Configure Synapse to use an email server (details follow). * Run or choose an


Reflow formatting fail?

UPGRADE.rst

richvdh · 2019-09-25T12:36:15Z

UPGRADE.rst

+Following upgrade, to continue sending email (and therefore register via an
+email address) admins can either:-
+
+* Configure Synapse to use an email server (details follow). * Run or choose an


formatting has broken here

UPGRADE.rst

richvdh · 2019-09-25T12:39:17Z

UPGRADE.rst

+Delegate Email to an identity server
+------------------------------------
+
+Some admins will wish to continue using email as a registration method, but


it's not a registration method

UPGRADE.rst

richvdh · 2019-09-25T12:45:02Z

UPGRADE.rst

+will not immediately have an appropriate SMTP server to hand.
+
+To this end, we will continue to support email delegation via the vector.im and
+matrix.org identity servers for two months. The cut off date is Monday 2nd


Support for delegated email verification will be disabled on Monday 2nd December.

richvdh · 2019-09-25T13:00:18Z

UPGRADE.rst

+---
+
+Following upgrade, the only way to maintain the ability to send SMS (and
+therefore register via a phone number) will be to continue to delegate SMS


s/SMS delivery/phone number verification/

richvdh · 2019-09-25T13:01:14Z

UPGRADE.rst

@@ -114,7 +226,8 @@ v1.3.1, subject to the following:
  The room statistics are essentially unused in v1.3.1 (in future versions of
  Synapse, they will be used to populate the room directory), so there should
  be no loss of functionality. However, the statistics engine will write errors
-  to the logs, which can be avoided by setting the following in `homeserver.yaml`:
+  to the logs, which can be avoided by setting the following in
+  `homeserver.yaml`:


I don't see the problem, am wrapping to 80 chars.

richvdh · 2019-09-25T13:01:19Z

UPGRADE.rst

@@ -124,6 +237,7 @@ v1.3.1, subject to the following:
  Don't forget to re-enable it when you upgrade again, in preparation for its
  use in the room directory!

+


richvdh · 2019-09-25T13:01:36Z

UPGRADE.rst

+server that supports SMS sending).
+
+
+The ``account_threepid_delegates`` dictionary defines whether the homeserver


see comments above, though I'd love it if we could avoid repeating this

I'm just not sure I see a neat way not to repeat, since it is convenient to have the context close the description of what changes the admin must make. My sense is that since this is not a doc that needs maintenance the repetition is permissible, if you can see a better way to do it, just edit direct.

richvdh · 2019-09-25T13:01:54Z

UPGRADE.rst

+<https://matrix.org/docs/spec/identity_service/r0.2.1>`_) to handle sending
+password reset or registration messages via email and SMS.
+
+So to delegate SMS sending set ``account_threepid_delegates.msisdn`` to a base


gtg, I think there are similar comments to be made below

Co-Authored-By: Andrew Morgan <[email protected]> Co-Authored-By: Richard van der Hoff <[email protected]>

…nto neilj/upgrade_notes

neilisfragile

LGTM - SHIP IT!!!!!

neilisfragile added 3 commits September 12, 2019 13:54

wip clarifications to the 1.4 upgrade notes

b6913a9

towncrier

275fdf4

fix rendering bugs

299f99b

neilisfragile changed the base branch from master to develop September 13, 2019 10:03

neilisfragile requested a review from a team September 13, 2019 10:04

anoadragon453 suggested changes Sep 13, 2019

View reviewed changes

neilisfragile and others added 6 commits September 13, 2019 11:46

Update UPGRADE.rst

44cc8ee

Co-Authored-By: Andrew Morgan <[email protected]>

Update UPGRADE.rst

df4d30e

Co-Authored-By: Andrew Morgan <[email protected]>

Update UPGRADE.rst

e234785

Co-Authored-By: Andrew Morgan <[email protected]>

Update UPGRADE.rst

562be3a

Co-Authored-By: Andrew Morgan <[email protected]>

Update UPGRADE.rst

c146172

Co-Authored-By: Andrew Morgan <[email protected]>

Update UPGRADE.rst

f48e209

Co-Authored-By: Andrew Morgan <[email protected]>

Update UPGRADE.rst

b2aeffd

Co-Authored-By: Andrew Morgan <[email protected]>

JorikSchellekens reviewed Sep 14, 2019

View reviewed changes

UPGRADE.rst Outdated Show resolved Hide resolved

UPGRADE.rst Outdated Show resolved Hide resolved

UPGRADE.rst Outdated Show resolved Hide resolved

neilisfragile changed the title ~~Neilj/upgrade notes~~ Clarified upgrade notes ahead of 1.4 release Sep 16, 2019

richvdh changed the title ~~Clarified upgrade notes ahead of 1.4 release~~ Clarify upgrade notes ahead of 1.4 release Sep 18, 2019

anoadragon453 mentioned this pull request Sep 18, 2019

Implement MSC2290 #6043

Merged

richvdh mentioned this pull request Sep 18, 2019

Allow HS to send emails when adding an email to the HS #6042

Merged

add reference to new email templates

005b626

richvdh suggested changes Sep 18, 2019

View reviewed changes

neilisfragile and others added 4 commits September 18, 2019 17:37

For clarity

8ed2a8e

Co-Authored-By: Richard van der Hoff <[email protected]> Co-Authored-By: Andrew Morgan <[email protected]>

clarifications

3bb7413

fix merge conflicts

830fdef

Merge branch 'develop' of github.com:matrix-org/synapse into neilj/up…

6f173e9

…grade_notes

babolivier suggested changes Sep 19, 2019

View reviewed changes

UPGRADE.rst Outdated Show resolved Hide resolved

UPGRADE.rst Outdated Show resolved Hide resolved

UPGRADE.rst Outdated Show resolved Hide resolved

UPGRADE.rst Outdated Show resolved Hide resolved

changelog.d/6027.doc Outdated Show resolved Hide resolved

Apply suggestions from code review

9719aea

Co-Authored-By: Richard van der Hoff <[email protected]>

neilisfragile added 3 commits September 19, 2019 17:38

clarity

12a8a93

Merge branch 'neilj/upgrade_notes' of github.com:matrix-org/synapse i…

1ce9a42

…nto neilj/upgrade_notes

word wrap

7bdf545

neilisfragile requested a review from richvdh September 23, 2019 14:43

neilisfragile changed the title ~~Clarify upgrade notes ahead of 1.4 release~~ Clarify upgrade notes ahead of 1.4.0 release Sep 23, 2019

neilisfragile added the release blocker label Sep 24, 2019

specify the cut off date for IS email delegation

1806fda

richvdh suggested changes Sep 24, 2019

View reviewed changes

neilisfragile and others added 3 commits September 24, 2019 21:35

Apply suggestions from code review

7e50237

Improve clarity Co-Authored-By: Richard van der Hoff <[email protected]>

clarity

03608b1

Merge branch 'neilj/upgrade_notes' of github.com:matrix-org/synapse i…

22d94a6

…nto neilj/upgrade_notes

richvdh reviewed Sep 25, 2019

View reviewed changes

anoadragon453 suggested changes Sep 25, 2019

View reviewed changes

richvdh suggested changes Sep 25, 2019

View reviewed changes

Apply suggestions from code review

0548e65

Co-Authored-By: Andrew Morgan <[email protected]> Co-Authored-By: Richard van der Hoff <[email protected]>

richvdh assigned neilisfragile Sep 26, 2019

neilisfragile and others added 9 commits September 26, 2019 11:02

clarity

f94937e

move custom templates away from threepid delegation section

b8042d6

formatting

1f059b6

rejig custom templates to be at the top

bfda23b

Merge branch 'neilj/upgrade_notes' of github.com:matrix-org/synapse i…

ab77a61

…nto neilj/upgrade_notes

place holder blog reference

77c4989

rearrange sections again

7783bc1

more editing tweaks

f954075

remove blog link

4d626ff

neilisfragile commented Sep 26, 2019

View reviewed changes

neilisfragile merged commit 1b23f99 into develop Sep 26, 2019

neilisfragile deleted the neilj/upgrade_notes branch September 26, 2019 11:30

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Clarify upgrade notes ahead of 1.4.0 release #6033

Clarify upgrade notes ahead of 1.4.0 release #6033

neilisfragile commented Sep 13, 2019 •

edited by richvdh

Loading

anoadragon453 left a comment

anoadragon453 Sep 13, 2019

anoadragon453 commented Sep 13, 2019

richvdh commented Sep 13, 2019

anoadragon453 commented Sep 17, 2019

anoadragon453 commented Sep 18, 2019

richvdh left a comment

babolivier left a comment

richvdh Sep 24, 2019

neilisfragile Sep 24, 2019

richvdh Sep 25, 2019

richvdh Sep 25, 2019

richvdh Sep 25, 2019

richvdh Sep 25, 2019

richvdh Sep 25, 2019

anoadragon453 Sep 25, 2019

richvdh Sep 25, 2019

richvdh Sep 25, 2019

richvdh Sep 25, 2019

richvdh Sep 25, 2019

richvdh Sep 25, 2019

neilisfragile Sep 26, 2019

richvdh Sep 25, 2019

richvdh Sep 25, 2019

neilisfragile Sep 26, 2019

richvdh Sep 25, 2019

neilisfragile left a comment

		@@ -124,6 +237,7 @@ v1.3.1, subject to the following:
		Don't forget to re-enable it when you upgrade again, in preparation for its
		use in the room directory!

		server that supports SMS sending).


		The ``account_threepid_delegates`` dictionary defines whether the homeserver

Clarify upgrade notes ahead of 1.4.0 release #6033

Clarify upgrade notes ahead of 1.4.0 release #6033

Conversation

neilisfragile commented Sep 13, 2019 • edited by richvdh Loading

anoadragon453 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

anoadragon453 commented Sep 13, 2019

richvdh commented Sep 13, 2019

anoadragon453 commented Sep 17, 2019

anoadragon453 commented Sep 18, 2019

richvdh left a comment

Choose a reason for hiding this comment

babolivier 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

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

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

Choose a reason for hiding this comment

neilisfragile left a comment

Choose a reason for hiding this comment

neilisfragile commented Sep 13, 2019 •

edited by richvdh

Loading