Hi, community. I am posting to this mailing list a proposal to remove the config-default.yaml default configuration file, and below I will describe the background and reasons for this and consider the benefits to us.
The proposal does not represent a community resolution, although I am a committer in the APISIX community. We still want to hear a variety of voices to make sure this is truly beneficial. *# Background* Now APISIX has two configuration files, the user configuration file *config.yaml* and the default configuration file *config-default.yaml*. When APISIX starts up, it reads these two configuration files and merges and overwrites the user configuration file with the default configuration to create the configuration that is actually used at runtime. The recommendation from the developers is that users should only modify the user configuration file *config.yaml*, while ensuring that *config-default.yaml* remains intact. This is documented here: https://apisix.apache.org/docs/apisix/next/installation-guide/ > APISIX's default configuration can be found in conf/config-default.yaml file and it should not be modified. > It is bound to the source code and the configuration should only be changed by the methods mentioned above. Users often ask how they should modify custom configurations, or encounter unintended problems after modifying the default configuration file. When explaining to them why they should not modify the default configuration file but copy those keys that need to be modified to the user configuration file and then modify them, and explaining the logic of merging the user configuration file with the default configuration file, I do find this issue to be a troubling one. Also, some PRs encountered errors when improving config-default.yaml. For example: https://github.com/apache/apisix/pull/11284 Let's shift our attention to other major open source projects in the world, I have indeed seen very few implementations with such built-in annoyances. Often software can have its default configuration hard-coded into the program, bundled into a binary for distribution, and the user can use a new configuration file, which they will load at runtime and override the modified keys into the default configuration. This way, the user only needs to remember that he should modify *config.yaml* and nothing else; and APISIX will start normally without providing any configuration. This really reduces the cost of understanding. Therefore, I suggest the following. *# Proposal* 1. Remove *config-default.yaml* and move its contents to a Lua file as a Lua table 2. Fix test errors 3. Use documentation to explicitly document all configuration items, which ideally should be generated from the schema. This is APISIX enhancement work, which is not perceived by users unless they are using APISIX in a non-correct way. *# Benefit* 1. Reduce the cost of explaining about the section, and the cost of understanding for the user. 2. Reduce the APISIX code base 3. Improve the documentation quality through the entire process. *# The End* The discussion is asking for feedback, and you can reply to the email directly to the mailing list. We can discuss constructive feedback. If there is no constructive feedback, I will start working on it. -- Best regards! Zeping Bai @bzp2010
