From 170987381993e97efdd02b07c0c2e6ecf2c8e15c Mon Sep 17 00:00:00 2001 From: Mute Date: Mon, 21 Aug 2023 01:23:01 +0000 Subject: [PATCH] Add 'RFC: settings' --- RFC%3A-settings.md | 113 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 113 insertions(+) create mode 100644 RFC%3A-settings.md diff --git a/RFC%3A-settings.md b/RFC%3A-settings.md new file mode 100644 index 0000000..9ca262e --- /dev/null +++ b/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. +