Clarify vendor prefixing requirements

[Johennes]

Following the discussion in matrix-org/matrix-spec-proposals#4335 (comment), this is an attempt to clarify the requirements for vendor prefixing. This PR includes the following changes:

• Broke description of unstable endpoints / features and vendor prefixes out of the list into a subsection.
  The nested bullets were already quite long before making it hard to follow the outer list.
• Clarified that org.matrix being "recommended" doesn't apply to the general public.
• Added examples of how to use prefixes in request parameters, JSON objects and enumerations.
  These stem from my own observations of how people used prefixes in the past.

The proposals section doesn't seem to have its own changelog category, so I picked internal.

Aaaand looks like I scored the #2222 pull request! 🎉😅

Pull Request Checklist

• Pull request includes a changelog file
• Pull request includes a sign off
• Pull request is classified as 'other changes'

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

[hughns]

https://spec.matrix.org/v1.16/client-server-api/#standard-error-response suggests that ORG.MATRIX.MSCXXXX_INVALID_EMAIL would be the correct prefix.

[turt2live]

• Replaced com.example in examples with org.matrix given that the text calls it out as the recommended prefix.

The Foundation's preferred prefix is documented primarily for ourselves - it's not intended to be used in examples. It's also not recommended for folks outside the Foundation to use the Foundation's prefix.

[Johennes]

The Foundation's preferred prefix is documented primarily for ourselves - it's not intended to be used in examples. It's also not recommended for folks outside the Foundation to use the Foundation's prefix.

Oh! I guess everybody is doing it wrong all the time then. 😯

If this is only for Foundation staff / SCT members, should it even be mentioned in the docs here? And what prefix should people without ownership of a domain use?

[turt2live]

in the Java world, people typically use com.github.YOUR_USERNAME.

The Foundation's (not just SCT's) namespace should remain in the spec, but clarified that it's an example of how one might want to structure their own namespace.

[Johennes]

So Foundation staff and SCT get to use org.matrix? (Asking to be able to properly unpack "recommended" when replacing the current text.)

[turt2live]

Anyone operating under the Foundation should be using org.matrix - this covers staff, the SCT, governing board (if doing spec work), and contractors.

[Johennes]

Have changed the text accordingly. We might want to make some noise about this as I don't believe many people follow it in practice and I have never seen it flagged in proposal review.

[KitsuneRal]

A couple of nitpicks.