Merge pull request #3549 from ElektraInitiative/decisions

Decisions

.github/PULL_REQUEST_TEMPLATE.md

@@ -9,7 +9,11 @@ These points need to be fulfilled for every PR:
 - [ ] Details of what you changed are in commit messages
       (first line should have `module: short statement` syntax)
 - [ ] References to issues, e.g. `close #X`, are in the commit messages.
-- [ ] The buildservers are happy.
+- [ ] The buildservers are happy. If not, fix **in this order**:
+  - [ ] add a line in `doc/news/_preparation_next_release.md`
+  - [ ] reformat the code with `scripts/dev/reformat-all`
+  - [ ] make all unit tests pass
+  - [ ] fix all memleaks
 - [ ] The PR is rebased with current master.
 
 If you have any troubles fulfilling these criteria, please write

README.md

@@ -20,6 +20,7 @@ applications' configurations, leveraging easy application integration.
 
 ## Often Used Links
 
+- If you are new, start reading [Get Started](doc/GETSTARTED.md)
 - [Build server](https://build.libelektra.org/)
 - [Website](https://www.libelektra.org)
 - [API documentation](https://doc.libelektra.org/api/latest/html/)

doc/GETSTARTED.md

@@ -59,10 +59,15 @@
   cmake ..  # watch output to see if everything needed is included
   #  optionally run "ccmake .." to get an overview of the available build settings (needs cmake-curses-gui)
   cmake --build build -- -j5
-  cmake --build build --target run_nokdbtests #optional: run tests
   ```
 
-  With these commands you will be able to run the "Hello World!" example but usually you will need to use some of the [plugins](/src/plugins/README.md), tools and bindings of Elektra. Please take a look to the more detailed [compiling documentation](/doc/COMPILE.md). After you completed building Elektra on your own, you can execute these commands to install Elektra (please check the [installation documentation](/doc/INSTALL.md) if you are using Debian):
+  Optionally you can also run tests, see [here for more information](/doc/TESTING.md):
+
+  ```sh
+  cmake --build build --target run_nokdbtests
+  ```
+
+  With these commands you will be able to run the "Hello World!" example but usually you will need to use some of the [plugins](/src/plugins/README.md), tools and bindings of Elektra. Please take a look at the more detailed [compiling documentation](/doc/COMPILE.md). After you completed building Elektra on your own, you can execute these commands to install Elektra (please check the [installation documentation](/doc/INSTALL.md) for the many available packages):
 
   ```sh
   sudo make install
@@ -71,7 +76,13 @@
 
   [Installation documentation](/doc/INSTALL.md) contains further information about available packages.
 
+  Optionally you can also run tests to verify the installed Elektra, see [here for more information](/doc/TESTING.md):
+
+  ```sh
+  kdb run_nokdbtests
+  ```
+
 - Hello World!
 
-  Start with your very first Elektra application and follow these steps:
+  Start with your very first Elektra application in C and follow these steps:
   [Hello World!](/doc/tutorials/hello-elektra.md)

doc/METADATA.ini

@@ -59,7 +59,7 @@ version/minor=6
 
 #
 # Important metadata often used in configuration files
-# (and seldom in specifications)
+# and not used in specifications.
 #
 
 [order]
@@ -153,14 +153,18 @@ description= The spaces/tabs used between a comment and the beginning of the
 example=
 
 
-
-
-[line]
-type= int
-status= proposal
-description= contains the line number from which a key was read.
-note= is useful for validation problems when someone directly
-	edits files
+[internal/<plugin>/*]
+status= implemented
+usedby/plugin=
+description= Internal metadata that must be ignored by other plugins.
+	It is useful for reconstruction of information about keys between
+	kdbGet and kdbSet.
+	Always avoid to use it if there is any other metadata that
+	can be used instead.
+	For example, if a type can be represented with the CORBA
+	type system, metadata `type` should be used.
+	Only if a type cannot be represented, e.g., the `toml`
+	plugin would use `internal/toml/type`.
 
 
 
@@ -255,7 +259,7 @@ description= For this metadata only the presence is significant, not its value.
 
 [array]
 type= array-index
-status= proposed
+status= implemented
 description= Such keys have only keys conforming to Elektra’s arrays convention as subkeys.
 	If the metavalue is empty, the array is empty (no subkeys).
 	Otherwise the metavalue contains the last element.
@@ -300,9 +304,9 @@ note=  It is generally preferred that other metadata will be used to
 	deduce the needs of the specification, e.g. use check/validation
 	metadata instead of as given above.
 
-[config]
+[config/needs]
 type= string
-status= proposed
+status= implemented
 description= indicate that the mount point needs some
 	configuration for plugins in order to work.
 
@@ -753,18 +757,6 @@ description = a number of warnings, see src/error/specification
 
 
 
-#
-# Struct validation
-#
-
-
-[struct]
-type = vector <string>
-status = proposed
-description = checks if the subkeys form a valid struct with the given
-	names.
-	The validator makes sure that there are no keys for the struct missing.
-example = device mpoint type options [dumpfreq] [passno]
 
 
 #
@@ -962,12 +954,6 @@ type= string
 description= A ternary conditional style operator to define
 	relations between keys
 
-[condition/validsuffix]
-status= proposal
-usedby/plugin= conditionals
-type= string
-description= A unit of measure style prefix
-
 [check/condition/any/#]
 status= implemented
 usedby/plugin= conditionals
@@ -986,6 +972,12 @@ usedby/plugin= conditionals
 type= string
 description= An array of multiple condition statements
 
+[condition/validsuffix]
+status= implemented
+usedby/plugin= conditionals
+type= string
+description= A unit of measure style prefix
+
 [assign/condition]
 status= implemented
 usedby/plugin= conditionals
@@ -1051,7 +1043,7 @@ description= Trigger an error with given error number from src/error/specificati
 [trigger/error/nofail]
 usedby/plugin= error
 type= long
-status= proposal
+status= implemented
 description= Add the error but do not fail (to test robustness of framework).
 
 [check/macaddr]
@@ -1069,10 +1061,6 @@ status= idea
 description= Flag keys that will be removed in further versions
 note= thanks to Config::Model for that idea
 
-[internal/<plugin>/*]
-status= implemented
-description= Internal metadata to be ignored by other plugins.
-
 [source]
 status= idea
 description= states where a key comes from if it is not from an ordinary

doc/decisions/README.md

@@ -37,26 +37,34 @@ section here.
 - [High Level API](high_level_api.md)
 - [Error codes](error_codes.md)
 - [Error code implementation](error_code_implementation.md)
+- [Semantics for Name](semantics_name.md)
+- [Base Name](base_name.md)
+- [Lookup every key](lookup_every_key.md)
+- [Holes and Non-leaf values](holes.md)
+- [Multiple File Backends](multiple_file_backends.md)
+- [Boolean](boolean.md)
+
+## In Progress
+
+- [Global Plugins](global_plugins.md) (@mpranj)
+- [Ensure](ensure.md) (@kodebach)
+- [Capabilities](capabilities.md) (@markus2330)
+- [Error Semantics](error_semantics.md) (API)
 
 ## Decided
 
 - [Array for Warnings](warning_array.md)
+- [Array](array.md)
 
 ## In Discussion
 
-- [Semantics for Name](semantics_name.md)
-- [Base Name](base_name.md)
+- [Escaped Name](escaped_name.md) merge with:
 - [Store the escaped and/or unescaped key name](store_name.md)
-- [Sources for Metadata](metadata_sources.md)
-- [Lookup every key](lookup_every_key.md)
-- [Holes and Non-leaf values](holes.md)
-- [Arbitrary Meta-Data](arbitrary_metadata.md)
-- [Multiple File Backends](multiple_file_backends.md)
-- [Capabilities](capabilities.md)
-- [Array](array.md)
-- [Boolean](boolean.md)
-- [Global Plugins](global_plugins.md)
-- [Vendor Spec](vendor_spec.md)
+- [Spec Expressiveness](spec_expressiveness.md)
+- [Metadata in Spec Namespace](spec_metadata.md)
+
+## Delayed
+
 - [Plugin Variants](plugin_variants.md)
 - [Global Validation](global_validation.md)
 
@@ -66,3 +74,4 @@ section here.
 - [Null Pointer Checks](null_pointer_checks.md)
 - [Elektra Web Publish Subscribe](elektra_web_pubsub.md)
 - [Internal Cache](internal_cache.md)
+- [Vendor Spec](vendor_spec.md)

doc/decisions/array.md

@@ -24,6 +24,10 @@ an array or not.
 ## Decision
 
 Store length in metadata `array` of key, or keep metadata `array` empty if empty array.
+Only children that have `#` syntax are allowed in a valid array.
+The index start with `#0`.
+Both `keyAddName("#12")` or `keyAddBaseName("#_12")` is allowed to add the 13th index.
+
 For example (`ni syntax`, sections used for metadata):
 
 ```
@@ -40,8 +44,8 @@ myarray/#5 = value5
 It is not allowed to have anything else than `#5` in the metadata `array`,
 e.g. even `#4` would be a malformed array.
 
-The metadata `array` preferable should be in `spec` (specified configuration).
-Then the `spec` plugin will add the `array` marker with the correct length.
+With the metadata `array` in `spec:/` the `spec` plugin will add the
+`array` marker with the correct length.
 This needs to be happen early, so that plugins can rely on having
 correct arrays.
 
@@ -76,12 +80,12 @@ user:/myarray/#0
 system:/myarray  # <- not found in cascading lookup, as user:/myarray exists
 ```
 
-Guarantees we want from the spec plugin:
+The `spec` plugin should check if it is a valid array, i.e.:
 
-- that the parent key always contain `array`.
-- that the correct length is in `array`
-- that the array only contains `#` children
-- that the children are numbered from 0 to n, without holes
+- that the parent key always contains the metadata `array`,
+- that the correct length is in `array`,
+- that the array only contains `#` children, and
+- that the children are numbered from `#0` to `#n`, without holes.
 
 ## Rationale
 
@@ -98,11 +102,17 @@ Guarantees we want from the spec plugin:
   which is a possibility also in all the alternatives of this decision.
 - A `user:/` or `dir:/` key can change the semantics of a `system:/` array,
   if not avoided by `spec`.
+- user-facing documentation should contain a note like:
+  "Mixing array and non-array keys in arrays is not supported.
+  In many cases the trivial solution is to move the array part into a separate child-key."
 
 ## Related Decisions
 
 - [Global Plugins](global_plugins.md)
 - [Global Validation](global_validation.md)
+- [Base Names](base_name.md)
+- [Metadata in Spec Namespace](spec_metadata.md)
+- [Spec Expressiveness](spec_expressiveness.md)
 
 ## Notes