Consider supplying a more complete example configuration file

[richvdh]

#12941 replaced the generated 2850-line sample configuration file with a very bare-bones starting point.

I still believe that was a good decision for all the reasons set out in #8159 , however a lot of people have found it surprising so I am opening this issue as a place to discuss whether there is a sensible middle ground.

One thing that might be worthwhile is an example file containing some of the settings you are likely to need to configure (eg: url previews, turn server) without attempting to be comprehensive. The CUPS project does something like this (it generates an example cupsd.conf from https://github.com/OpenPrinting/cups/blob/master/conf/cupsd.conf.in; the authoritative documentation is managed separately at https://github.com/OpenPrinting/cups/blob/master/man/cupsd.conf.5).

[richvdh]

The CUPS project does something like this

does anyone know of other projects doing this sort of thing? I'm not necessarily sure I want to hold up CUPS as the poster-child of easy-to-configure systems :-S

[nico-famedly]

does anyone know of other projects doing this sort of thing? I'm not necessarily sure I want to hold up CUPS as the poster-child of easy-to-configure systems :-S

The turnserver project generates a whole example directory: https://github.com/coturn/coturn/tree/master/examples

Imo their example is missing a few settings you should configure, but it exists at least and has some subset of options, not necessarily the best subset though.

[redrikshuhartart]

Please return the config file as it was. We are already used to it. I have to set up new matrix-synapse instances often, so I do it automatically. Constant changes in the config file force scripts to be rewritten. Yes, the old config file was large, but it was well documented.

[immanuelfodor]

I also vote for bringing back the old big but transparent config file with all the available options and the documentation included in it. The config removal and the separation of docs and code made me to trust my Homeserver less.

[deffcolony]

Ive followed a YouTube tutorial:

I am unable to correctly follow the video without the right homeserver.yaml generated file... I would like to request bringing back the old over 2000 lines config file

For now ive used this link to fix the problem:
https://github.com/matrix-org/synapse/blob/v1.61.1/docs/sample_config.yaml

[richvdh]

related: #13385

[richvdh]

The CUPS project does something like this

does anyone know of other projects doing this sort of thing? I'm not necessarily sure I want to hold up CUPS as the poster-child of easy-to-configure systems :-S

Looks like redis also does this: https://github.com/redis/redis/blob/unstable/redis.conf

[witchent]

Assume we are happy with the default value right now for some key, but the default is changed for some reason (e.g. room version, but I'm sure there is a better example) or a new option is introduced, how do we best follow those changes? I used to just diff the configs, but this won't work anymore, so is the only option to check the changelogs carefully and hope you don't miss any config change?

[immanuelfodor]

I'm doing a git diff on the config docs from the previous version to the latest commit, but this is inefficient to do after each release, and still, these are just the changes, not the complete example config file:

VERSION=v1.91
git clone --depth 1 https://github.com/matrix-org/synapse
git -C synapse diff origin/release-$VERSION HEAD docs/usage/configuration/config_documentation.md
rm -rf synapse

[richvdh]

Assume we are happy with the default value right now for some key, but the default is changed for some reason (e.g. room version, but I'm sure there is a better example) or a new option is introduced, how do we best follow those changes?

I am really tired of this discussion. It has been done to death in #8159. This issue is not the place to keep discussing it; but in short, I don't agree "new config options" and "changed defaults" are so much more important to know about than literally any other change in Synapse that they need their own special process for announcing them.

If your config works for Synapse 1.91 it will work just fine in 1.92; in the very rare situation this is not the case, we will do our very best to announce it widely. If you miss the introduction of some esoteric config option, who the hell cares?

If you want to comment on it further I suggest you take it back to #8159. This issue is about shipping an example config file, which by definition would not be comprehensive (and hence not helpful for your usecase).