Upgrade from 1.61 to 1.62.0 provides sample file for homeserver.yaml

[Sakrecoer]

Description

I've installed the Debian/ubuntu version with the packages provided via https://packages.matrix.org/debian/.

So far, i've always chosen to inspect the new configuration file that is shipped because some changes are cool. Often i chose to pick the package managers version and adapt it with my settings afterwards.

This time the file that apt wants to put there is https://github.com/matrix-org/synapse/blob/develop/docs/sample_config.yaml

Steps to reproduce

• sudo apt update && sudo apt upgrade
• when prompted about the new version of the config file, chose inspect
• the file provided is the sample_config.yaml

Homeserver

m.basspistol.org

Synapse Version

1.62.0

Installation Method

Apt via https://packages.matrix.org/debian/.
https://matrix-org.github.io/synapse/latest/setup/installation.html#debianubuntu

Platform

Ubuntu

Relevant log output

There are no relevant log i can think of for this issue

Anything else that would be useful to know?

No response

[stonie08]

I noticed that as well. So far I've used a mergetool to inspect any changes and adapt new flags into my config. Now this becomes much more of a hassle.

[behrmann]

I actually welcome the change, since the fully annotated homeserver.yaml had become a bit unwieldy, but only looking at the online documentation has one major downside for me as an admin: it's harder to follow changes to the config.

It would be great to add new in version 1.foo.bar there, like e.g. the Python stdlib documentation does. This would make it much easier to just grep the docs after each release for what's new in the file and what new options one can add to ones config.

[DMRobertson]

The motivation for this change is explained in #8159. I'm going to close this and ask that further discussion take place on that issue.

FWIW, the best reference for changes are the changelog and the admin-specific upgrade notes. Perhaps we should highlight new config options in the upgrade notes?

[behrmann]

FWIW, the best reference for changes are the changelog and the admin-specific upgrade notes. Perhaps we should highlight new config options in the upgrade notes?

The changelog is not the right place for this as - I think - it lists every merged PR and if one doesn't intend to be so on top of development as to read all PR discussions it would be hard to use this to find new or changed config options. :) Adding new config options to the upgrade notes would be just as well as adding it to the configuration manual, though.

[richvdh]

see also #13306