Replace authorization with authorisation throughout the spec

[richvdh]

The style guide requires en_GB, which spells authorisation with an s.

Preview: https://pr2351--matrix-spec-previews.netlify.app

[richvdh]

I created this in response to the pushback against MSC4421, in the hope that it might help us visualise what we're talking about when people suggest going back to en_GB.

I think it's tolerable, even if it feels a bit odd that, say grant_types_supported uses authorization_code to identify the authorisation code grant.

@sandhose as our resident OAuth2 expert, I'd welcome your thoughts on this.

[turt2live]

lgtm, assuming this doesn't cause problems in OAuth areas.

[hughns]

Two things:

Firstly, there are some clear errors in here which need to be addressed where constants have been renamed. See comments inline, but I could well have missed some more.

Secondly, for the OAuth related items sometimes/often we are referring to concepts or entities that are defined in external specs (e.g. RFCs). In these cases it doesn't feel "right" to have renamed them.

Examples of things that are external concepts:

• "Authorization Code": https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.1
• "Authorization Code Grant": https://datatracker.ietf.org/doc/html/rfc6749#section-4.1
• "Device Authorization Grant": https://datatracker.ietf.org/doc/html/rfc8628
• "Authorization Request": https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.1
• "Authorization Response": https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2
• "OAuth 2.0 Authorization Server Metadata": https://datatracker.ietf.org/doc/html/rfc8414
• "Device Authorization Request": https://datatracker.ietf.org/doc/html/rfc8628#section-3.1
• "Device Authorization Response": https://datatracker.ietf.org/doc/html/rfc8628#section-3.2

Ideas:

• we treat these external things as proper names that cannot be changed
• we make it clearer when we are referring to the proper name or not. e.g. instead of the heading "Authorization Request" perhaps "Sending the Authorization Request" with a note that this is an Authorization Request as defined by XYZ.

[richvdh]

Firstly, there are some clear errors in here which need to be addressed where constants have been renamed. See comments inline, but I could well have missed some more.

Good spots, thank you. I tried really hard to avoid changing these, so I'm sorry I missed them :/.

Secondly, for the OAuth related items sometimes/often we are referring to concepts or entities that are defined in external specs (e.g. RFCs). In these cases it doesn't feel "right" to have renamed them.

Right, so this is the whole debate here. matrix-org/matrix-spec-proposals#4421 (comment) is the relevant thread.

we treat these external things as proper names that cannot be changed

I'm really not in favour of trying to use en_US terms when we are talking about OAuth things, and en_GB the rest of the time. I did try that when the OAuth stuff first landed in the spec, but figuring out where exactly to draw the line was a nightmare. And you get sentences like "... obtain an authorisation code via the authorization code grant", which feels odd.

Further, the existence of https://auth0.com/fr/intro-to-iam/what-is-oauth-2 makes me think that one certainly can i18nise these terms.

we make it clearer when we are referring to the proper name or not. e.g. instead of the heading "Authorization Request" perhaps "Sending the Authorization Request" with a note that this is an Authorization Request as defined by XYZ.

I'm not really sure how practical this is. The problem is that these terms are repeated many times, and giving a reference each time they do is painful.

---

My only opinion here is that attempting a half-way house is unachievable; we should commit to one of en_GB or en_US. I don't really have a strong opinion on which, but I am a bit fed up with our current attempts to sit on the fence.

We got pushback against switching en_US, so this is my attempt to try en_GB. If you think this PR is worse, then I would welcome comments on MSC4421 :)

[richvdh]

Firstly, there are some clear errors in here which need to be addressed where constants have been renamed. See comments inline, but I could well have missed some more.

Good spots, thank you. I tried really hard to avoid changing these, so I'm sorry I missed them :/.

I ran this to double-check for further changes within identifiers:

$ git diff origin/main...HEAD | grep '^\+' | grep '`[^ `]*authoris'
$

[richvdh]

If you think this PR is worse, then I would welcome comments on MSC4421 :)

MSC4421 is in final call for closure.

[hughns]

The OAuth 2 API related changes now look sensible to me.