Document configuration option vocabulary/taxonomy and then simplify

[michaelkaye]

A document that contains the vocabulary of the synapse configuration and the expected values of those named fields would assist in keeping code consistent.

A few things have popped up recently, here and in other branches, so I thought i'd start an issue to collect examples.

I think we should first generate a statement on what the best naming scheme is for things, aim to apply that in future, then come back and deprecate/rename existing options to bring them into line.

Related issues:

• Rename email.riot_base_url config option #3913 (we should be clear this is used as a prefix or a template)
• Document the notif_from config parameter #2326 (we should be clear on what is a template and what isn't)
• Account for slash at the end of url in appservice config file #3523 (we should be consistent in requiring and handling trailing slashes in URLs in our configuration)

[michaelkaye]

For instance, we have secrets with different key names:

• pepper - a secret
• macaroon_secret_key - another secret
• registration_shared_secret - another secret

Secrets should be obviously a secret, and should match the form XXX_secret

We have:

• pid_file - a path to the writable pid file
• signing_key_path - a path to a readable secret file
• uploads_path - a path to a writable directory
• log_config - a path to a file, not a configuration itself.

All paths should match the form XXX_path if they're for directories
All paths should match the form XXX_file if they're to a single file

[michaelkaye]

We also have:

• turn_allow_guests- a boolean
• allow_guest_access - another boolean
• enable_metrics - a boolean
• disable_set_displayname - another boolean
• report_stats - a boolean.
• use_presence - another boolean

This should be something like "all boolean-type enabling options should use the format: "enable_XXX" (or if we want both enable and disable as defaultable things, prefix with "enable_XXX" or "disable_XXX") - but what we shouldn't do is mix enable, allow, use, report and so on.

[richvdh]

Another contender: durations:

• email.validation_token_lifetime
• key_refresh_interval
• account_validity.period
• account_validity.renew_at
• saml2.saml_session_lifetime
• stats.bucket_size
• stats.retention
• turn_user_lifetime
• rc_federation.sleep_delay

Most (all?) of the above can be expressed with units eg 6h, 2d.

• mau_trial_days (in days rather than milliseconds)

[ptman]

The sample config goes a long way. Could the comments just be improved and extended?

[richvdh]

vaguely related to #8159