From e95f90b251c0e9ef4df58d9f148b741c34881368 Mon Sep 17 00:00:00 2001 From: Igor Pashev Date: Mon, 13 Feb 2017 22:09:41 +0300 Subject: README on parameters --- README.md | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) (limited to 'README.md') diff --git a/README.md b/README.md index 27c9e59..c42415f 100644 --- a/README.md +++ b/README.md @@ -10,3 +10,43 @@ License This project is under the MIT license (see [LICENSE](LICENSE)), unless stated otherwise in individual files. + +Ideas +===== + + +Parametrization +--------------- + +Everything that _can_ be used at build time should have a parameter (integer, +string, path, etc.). Examples are TCP port, data directory, UNIX user. TCP +port can be used for configuring firewall or HTTP proxy, data directory can +be used for setting up mount points, UNIX user can be included into extra +groups, etc. When we have it all parametrized we do not repeat ourselves. + +Parametrization also helps modularity. I. e. you can define default set of +values and override only some of them in specific setups. + +Some applications accept only discrete set of options, in that case we should +parametrize them all. Examples are memcached, php-fpm and sproxy2. + +Parametrization should give access to all application features. Ideally, +parameters should exactly match to the application options, including +their names and meanings. Examples are MariaDB and PostgreSQL. This makes +documentation unnecessary, because each parameter is documented somewhere else. + +Almost every parameter, if it's not required by application (i. e. has +a built-in default value), should have value `null` by default. If such +parameter is not set, it is not passed to the application. This is twofold: +more transparency because we use _application's_ defaults (not ours), and it +is safer to use different versions of application, when particular options +may be added or removed. + +Even though, if the value of parameter is required at build time, the parameter +should have default value, preferably application's default. Example is +MariaDB's TCP port. We need it to configure firewall, thus we define it to +be 3306 by default. + +If application default value is known to be insecure, we should set our own, +_secure_, default value. + -- cgit v1.2.3