Add 'RFC: settings'

RFC%3A-settings.md

@@ -0,0 +1,113 @@
+# Meta
+Type: request for comments
+Title: mod settings
+
+
+# Problem domain
+Every mod with rare exceptions needs to deal with variable values -- either persistent or not -- that require user input. We'll call these "settings".
+Some examples of settings would be:
+
+* Whether or not to enable particular functionality
+* Preferred number of iterations of some loop
+* A text string to use in certain cases
+
+Noteably, it isn't correct to assume "settings" are what the user sees on a settings page of the club, more on that later.
+
+It is therefore proposed to unify the code that deals with settings in a separate library so that mod authors don't have to invent and implement
+their own incompatible ways to that end.
+
+Goals and non-goals list will be discussed later, after setting more context.
+
+
+# Entity analysis
+Fundamentally, these entities are at play:
+
+## Type
+Javascript is dynamic and weakly typed, but it does have types. Basically, for the purposes of this document, Type is twofold:
+
+* what actual JSON type will the value have
+* how to convert a string value (text that the user will input into the chat command) into an actual setting value
+
+## Emptiness
+Whether the value can be empty or not. The language around this question is confusing, because English isn't formal, while Javascript is,
+so more correct term would be "Nullableness", but it's quite unwieldy. To try to mitigate any confusion, formal emptiness will be marked
+with all caps, like this: EMPTY.
+
+The value is EMPTY if and only if one of the following is true:
+
+* Setting doesn't exist
+* Setting is null
+* Setting is undefined
+
+Noteably, zero or empty string or empty array or false aren't EMPTY values.
+
+## Default
+Often, though not always, it makes sense to have a value that is used instead of an EMPTY value. This value is a Default value.
+
+## Validator
+Tempting as it may be, defining custom types for values is unrealistic and serves no real purpose. Instead, any rules for determining
+valid values withing a given type constitute a validator.
+
+## Persistence
+Whether, and how, the value will persist between the user's club sessions. More on that later.
+
+## Setting
+Bringing all of the above together, a setting is a value of a particular type with emptiness specification, an optional default value,
+an optional validator, and a persistence specification.
+
+## Element
+An important part of the problem is dealing with UI/UX, including GUI. An element is a club GUI control that is associated with a setting.
+
+## Page
+Traditionally, GUI is organised using forms, but the club is much more centered around pages. A page is a collection of elements, with some
+important implications that will be, again, discussed later.
+
+## Migration
+Code tends to change. New settings are added, old are discarded, things move around. One can not simply design the ultimate data structure
+from the get go. Migrations declare mutations of settings scheme. Noteably, the initial state is blank, any setting there is should come from
+a migration, including the ones that are essential to the mod, are declared right away and never change later. No exceptions.
+
+
+# UI/UX analysis
+There are three main ways users interact with the club, all of them should be well supported:
+
+* club GUI
+* chat commands
+* browser console
+
+Let's go from simple to complex.
+
+## Browser console
+The browser gives us ready to use tools for a well established interaction pattern, all that needs to exist is a set of callable functions.
+Care should be taken to utilise autocomplete functionality where appropriate and affordable.
+
+## Chat commands
+Making a new command isn't a problem, the main challenge is making it easy to use, at least for people with a keyboard. Autocomplete is mandatory,
+however in absence of club native functionality it is proposed to outsource its mechanical implementation to a separate library, unless ready made
+options exist.
+
+## Club GUI
+On a surface level it looks like an easy problem to solve: just have a manifest with element coordinates, however there are edge cases that bring
+a lot of nuance. One example would be LSCG's collar buy-in, which is custom code not easily packed into a declarative manifest. Still, from the user's
+perspective the club GUI offers a well established, if quirky, pattern of interaction with, well, somewhat rich palette of elements to more or less
+satisfy all common types of values. It shouldn't be hard to make use of it.
+
+
+# Interoperability analysis
+As we propose a library, care should be taken to make it easy to use for actual mod authors to achieve everything (well, at least a sufficient part of)
+that they are now implementing independently.
+
+## Development time
+Mod authors should have access to the current API documentation, examples and typedefs in order to make use of the library.
+
+## Load time
+It is proposed to utilise FUSAM for load time dependency management, it should take care of everything, loading the library as a module and exposing it
+either as a global variable, or passing it to the mods that depend on it. As FUSAM itself is under development, the particularities of the load process
+is beyond the scope of this document.
+
+## Important note to consider
+This library may become a part of FUSAM itself, especially if FUSAM will make use of it.
+
+## Run time
+Having the module variable, mods can call the library API directly.
+