This is not really a bug but a really annoying behavior.

The debian package's configuration file change every time. Every time you update your synapse package, you have to go through the process of looking at the diff between the old and the new configuration file to check for relevant modifications. And often there are not.

For example when updating from 1.18.0+buster1 to 1.19.0+buster1 the changes where:

• a blank line removed
• the federation_ip_range_blacklist parameter and all its documentation position has changed
• some other not impacting changes

A very common and very frustrating change is the cosmetic one: removing (or adding) a space after a "#", fixing a typo, changing the indentation, …

This bother me every time I update my synapse. I also manage another one with an ansible playbook, and it makes me feel uncomfortable, because I have no way to known if I need to change my config file. Most of the time I do not change it, let it diverge from the one in the package, and every some months I go through the painful process of doing a full diff (btw finding the default conf is not obvious, the easiest way is to just to the update manually, going through the diff process with apt, and copy back the change to the config file in the ansible role).

My suggestion is that config files are not for documentation. That's a good idea when your config file is ten lines long and never changes, but that's not the case here. The nginx configuration documentation is not in the config file, neither the synapse one should. Please find somewhere else to put the doc, and leave our config file alone :p

If there is a relevant change, like an attribute changing name, or a new attribute, please indicate it in a changelog file (apt-listchanges will show it at installation). For everything else, like a documentation change or a typo fix, publish the new documentation somewhere but please (please!) don't do a config file diff.

Thanks you :)