Skip to content

Latest commit

 

History

History
722 lines (498 loc) · 32.5 KB

_preparation_next_release.md

File metadata and controls

722 lines (498 loc) · 32.5 KB
Raw

0.8.<> Release

This release did not happen yet.

Please update this file within PRs accordingly. For non-trivial changes, you can choose to be part of the highlighted changes. Please make sure to add some short tutorial (checked by shell recorder) or asciinema for highlighted items.

Please add your name at the end of every contribution. Syntax: (your name)

<<scripts/generate-news-entry>>

We are proud to release Elektra 0.8.<>.

What is Elektra?

Elektra serves as a universal and secure framework to access configuration settings in a global, hierarchical key database. For more information, visit https://libelektra.org.

You can also read the news on our website

Highlights

  • <>
  • <>
  • <>

Type (New Version)

The type plugin was completely rewritten in C. The old version is now called cpptype. (Klemens Böswirth)

The new type plugin also provides the functionality of the enum and the boolean plugin. These plugins are now considered obsolete and you should use type instead.

A few notes on compatibility:

  • the new type does not support the full feature set of enum and boolean, but it supports the features we consider useful.
  • the new type doesn't support FSType and empty. These have been deprecated for a long time and there are good alternatives available.
  • the new type supports enum, wchar and wstring as types, whereas the old cpptype would throw an error for these. In most cases this won't be a problem, but you should be aware of this breaking change.
  • the new type does not support check/type/min and check/type/max, please use the range plugin.

To switch from enum to the new type, you have to add either check/type=enum or type=enum. Without a check/type or type metakey, the type plugin will ignore the key. We now also support converting enum values to and from integer values (see README).

To switch from boolean to the new type, you don't have to do anything, if you used the default config. If you used a custom configuration please take a look at the README.

kdbEnsure

kdbEnsure is a new function in elektra-kdb. It can be used to ensure that a KDB instance meets certain clauses specified in a contract. In principle this a very powerful tool that may be used for a lot of things. For now it only supports a few clauses concerning plugins:

  • You can specify that a plugin should be mounted globally. This can for example be used to enable the new gopts plugin.
  • Conversely you can also define that a plugin should not be mounted globally, e.g. to disable the spec plugin, which is enabled by default.
  • Additionally you may want to enforce that a global plugin uses a certain configuration. For this case you can specify that the plugin should be remounted, i.e. unmounted and immediately mounted again.
  • Because of the different architecture involved, for now only unmounting of non-global plugins is supported.

All changes made by kdbEnsure are purely temporary. They will only apply to the KDB handle passed to the function.

IMPORTANT: kdbEnsure only works, if the list plugin is mounted in all appropriate global positions.

Note: kdbEnsure right now ignores the infos/recommends and infos/needs metadata of plugins, so you have to explicitly take care of dependencies. (Klemens Böswirth)

<>

Plugins

The following section lists news about the modules we updated in this release.

  • Support DOS newlines for the csvstorage plugin. (Vlad - Ioan Balan)

mINI

  • We fixed compiler warnings reported by GCC 9 in the unit test code of the plugin. (René Schwaiger)

YAJL

  • The plugin now allows setting a value to the mountpoint. This is represented as a top level value in JSON if no other key is present. (Philipp Gackstatter)

  • The plugin no longer lists empty parent keys with kdb ls. (Philipp Gackstatter)

  • The plugin signifies arrays with the metakey array according to the array decision. (Philipp Gackstatter)

  • The plugin no longer produces additional ___dirdata entries for empty array keys. See also issue #2477. (Philipp Gackstatter)

YAMBi

  • YAMBi is now able detect multiple syntax errors in a file. (René Schwaiger)

  • The error message now includes more information about the location of syntax errors. For example, for the incorrect YAML input config.yaml:

    key 1: - element 1
 - element 2
key 2: scalar
       - element 3

    , the plugin prints an error message that includes the following text:

    config.yaml:2:2: syntax error, unexpected start of sequence, expecting end of map or key
                  - element 2
                  ^
config.yaml:4:8: syntax error, unexpected start of sequence, expecting end of map or key
                        - element 3
                        ^

    . (René Schwaiger)

  • YAMBi now supports Elektra’s boolean data type. (René Schwaiger)

  • The plugin now handles YAML key-value pairs without a value at the end of a file correctly. (René Schwaiger)

  • The plugin now converts YAML key-value pairs with empty value to null/empty keys. (René Schwaiger)

  • YAMBi now converts empty files to a key set containing an empty version of the parent key. (René Schwaiger)

YAML CPP

  • The plugin now handles keys that are part of a map, but use a basename ending with array syntax correctly. For example, in a key set that contains keys with the following names:

    user/array/#0
user/array/#1
user/map/#0
user/map/key
user/map/#1

    , user/array/#0 and user/array/#1 represent array elements, while user/map/#0, and user/map/#1 do not, since the key set also contains the key user/map/key. The following Markdown Shell Recorder snippet shows the new behavior of the plugin:

    kdb mount config.yaml user yamlcpp
kdb set user/array/#0 one
kdb set user/array/#1 two
kdb set user/map/#0   three
kdb set user/map/key  four
kdb set user/map/#1   five
kdb file user | xargs cat
#> array:
#>   - one
#>   - two
#> map:
#>   "#0": three
#>   "#1": five
#>   key: four

    . (René Schwaiger)

  • YAML CPP now handles the conversion from and to Elektra’s boolean type properly. (René Schwaiger)

  • The plugin converts “sparse” key sets properly. For example, for the key set that contains only the key:

    • user/parent/#1/#2/map/#0 with the value arr

    and uses user/parent as parent key, YAML CPP stores the following YAML data:

    - ~
- - ~
  - ~
  - map:
      - arr

    .

  • YAML CPP now supports mixed data (nested lists & sequences) better. For example, the plugin now correctly converts the YAML data

    root:
  - element: one
  - element: two

    to the key set that contains the following keys:

    user/tests/yaml/root
user/tests/yaml/root/#0/element
user/tests/yaml/root/#1/element

    .

YAML Smith

  • YAML Smith now converts keys that shares a common prefix correctly. For example, the last command in the script:

    kdb mount config.yaml user/tests/yaml yaml
kdb set user/tests/yaml/common/one/#0 value
kdb set user/tests/yaml/common/two/#0 first
kdb set user/tests/yaml/common/two/#1 second
kdb export user/tests/yaml yamlsmith

    now prints the following YAML data:

    common:
  one:
    - "value"
  two:
    - "first"
    - "second"

    . (René Schwaiger)

  • The plugin now converts Elektra’s boolean values (0, 1) back to YAML’s boolean values (true, false). (René Schwaiger)

Yan LR

  • The build system now disables the plugin, if you installed a version of ANTLR 4 that does not support ANTLR’s C++ runtime (like ANTLR 4.5.x or earlier). (René Schwaiger)
  • We fixed an ambiguity in the YAML grammar. (René Schwaiger)
  • The build system now regenerates the modified parsing code, every time we update the grammar file. (René Schwaiger)
  • The plugin now reports the location of syntax errors correctly. (René Schwaiger)
  • The lexer for the plugin now emits start tokens for maps at the correct location inside the token stream. This update fixes a problem, where the plugin sometimes reported incorrect error messages for the first syntax error in a YAML file. (René Schwaiger)
  • Yan LR now supports Elektra’s boolean data type. (René Schwaiger)
  • The plugin now handles YAML key-value pairs that contain no value at the end of a file correctly. (René Schwaiger)
  • The plugin now converts YAML key-value pairs with empty value to null/empty keys. (René Schwaiger)
  • The plugin converts “empty” YAML files to a key set that contains an empty version of the parent key. (René Schwaiger)

YAwn

  • YAwn is now able to print error messages for multiple syntax errors. (René Schwaiger)

  • We also improved the error messages of YAwn, which now also contain the input that caused a syntax error. For example, for the input

    key: value
  - element

    the plugin prints an error message that contains the following text:

    config.yaml:2:3: Syntax error on input “start of sequence”
                   - element
                   ^

    . (René Schwaiger)

  • The plugin now supports Elektra’s boolean data type. (René Schwaiger)

  • YAwn handles YAML key-value pairs that contain no value at the end of a file correctly. (René Schwaiger)

  • The plugin now converts YAML key-value pairs with empty value to null/empty keys. (René Schwaiger)

  • YAwn now stores empty files as a key set containing an empty parent key. (René Schwaiger)

YAy PEG

  • YAy PEG now also supports PEGTL 2.8. (René Schwaiger)

  • The plugin now includes the input that could not be parsed in error messages. (René Schwaiger)

  • We improved the error messages for certain errors slightly. For example, the error message for the input

    "double quoted

    now includes the following text

    1:14: Missing closing double quote or incorrect value inside flow scalar
      "double quoted
                    ^

    . (René Schwaiger)

  • YAy PEG now supports compact mappings:

    - key1: value1
  key2: value2

    and compact sequences:

    - - element1
  - element2

    correctly. (René Schwaiger)

  • The plugin now supports Elektra’s boolean data type. (René Schwaiger)

  • YAy PEG now converts YAML key-value pairs with empty value to null/empty keys. (René Schwaiger)

  • The plugin now translates an empty file to a key set that contains a single empty parent key. (René Schwaiger)

Quickdump

  • quickdump is a new storage plugin. It implements a more concise form of the dump format, which is also quicker too read. Contrary to dump, quickdump only stores keynames relative to the parent key. This allows easy relocation of configurations. (Klemens Böswirth)

Reference

  • Fixed missing Metadata in README and METADATA.ini. (Michael Zronek)

Specload

  • The specload plugin is a special storage plugin. Instead of using a storage file it calls an external application to request its specification. For the transfer it relies on the quickdump plugin. (Klemens Böswirth)
  • Currently changing the specification is only allowed in a very limited way. However, in future the plugin should allow overriding a specification in all cases where this can be done safely. NOTE: While the plugin technically allows some modifications, because of a problem with the resolver this cannot be used right now (see limitations).
  • We also export elektraSpecloadSendSpec to abstract over the quickdump dependency. (Klemens Böswirth)

Syslog

  • We fixed an incorrect format specifier in a call to the syslog function. (René Schwaiger)

gOpts

  • The gopts plugin simply retrieves the values of argc, argv and envp needed for elektraGetOpts and then makes the call. It is intended to be used as a global plugin, so that command-line options are automatically parsed when kdbGet is called. (Klemens Böswirth)
  • The plugin works under WIN32 (via GetCommandLineW and GetEnvironmentString), MAC_OSX (_NSGetArgc, _NSGetArgv) and any system that either has a sysctl(3) function that accepts KERN_PROC_ARGS (e.g. FreeBSD) or when procfs is mounted and either /proc/self or /proc/curproc refers to the current process. If you need support for any other systems, feel free to add an implementation.

crypto / fcrypt

  • Empty GPG key IDs in the plugin configuration are being ignored by the crypto plugin and the fcrypt plugin. Adding empty GPG key IDs would lead to an error when gpg is being invoked.(Peter Nirschl)
  • Apply Base64 encoding to the master password, which is stored within the plugin configuration. This fixes a problem that occurs if ini is used as default storage (see 2591).(Peter Nirschl)

Cache

  • cache is a new global caching plugin. It uses mmapstorage as its storage backend and lazily stores keysets from previous ´kdbGet()´ calls. We added initial support for the default resolver and multifile resolver. (Mihael Pranjić)
  • Add check of resolved filenames, fixes false cache hits. (Mihael Pranjić)
  • Skip all plugins and global plugins when we have a cache hit. (Mihael Pranjić)
  • Temporarily remove cache from default global config, because of a bug (#2702 and #2694). (Mihael Pranjić)

mmapstorage

  • mmapstorage is now able to persist the Global KeySet, which is used by the cache plugin. (Mihael Pranjić)
  • Fixed support for kdb import and kdb export. (Mihael Pranjić)

semlock

removed due to:

  • constant pain
  • never worked properly
  • poor design
  • no time in future to maintain (Kurt Micheli)

RGBColor

  • New plugin to validate hex formatted colors (e.g. #fff or #abcd) and normalize them to rgba (4294967295 (= 0xffffffff) and 2864434397 (= 0xaabbccdd) respectively). It also has support for named colors according to the extended color keywords from CSS3. (Philipp Gackstatter)

Libraries

The text below summarizes updates to the C (and C++)-based libraries of Elektra.

Compatibility

As always, the ABI and API of kdb.h is fully compatible, i.e. programs compiled against an older 0.8 version of Elektra will continue to work (ABI) and you will be able to recompile programs without errors (API).

  • <>
  • <>
  • <>

Core

  • kdbGet now calls global postgetstorage plugins with the parent key passed to kdbGet, instead of a random mountpoint. (Klemens Böswirth)
  • Fixed a double cleanup error (segmentation fault) when mounting global plugins. (Mihael Pranjić)
  • Logging in Elektra was changed with this release. If Elektra is compiled with ENABLE_LOGGER enabled, we now log warnings and errors to stderr and everything except debug messages to syslog. If ENABLE_DEBUG is also enabled, debug messages are logged to syslog as well. Previously you had to make some manual changes to the code, to see most of the logging messages. (Klemens Böswirth)
  • The logger does not truncate the file name incorrectly anymore, if __FILE__ contains a relative (instead of an absolute) filepath. (René Schwaiger)
  • Disabled any plugin execution when we have a cache hit or no update from backends. The old behaviour can be enabled for testing using ENABLE_DEBUG and adding the "debugGlobalPositions" meta key to the parentKey of the kdbGet invocation. (Mihael Pranjić)
  • Removed ingroup from error messages to reduce verbosity. (Michael Zronek)
  • Fixed minor problem when kdb_long_double_t is not available (e.g. mips32). (Matthias Schoepfer)
  • <>

Ease

  • The functions for reference resolving used in the reference plugin have been extracted into libease. This lets other parts of Elektra easily use references and ensures a consistent syntax for them. (Klemens Böswirth)

<>

  • <>
  • <>
  • <>

<>

  • <>
  • <>
  • <>

Bindings

Bindings allow you to utilize Elektra using various programming languages. This section keeps you up to date with the multi-language support provided by Elektra.

  • JNA is now not experimental anymore. (Markus Raab)

  • gsettings is not default anymore. (Markus Raab)

  • Add fix for creating the Key and KeySet objects in the HelloElektra.java file (Dmytro Moiseiuk)

  • We fixed a warning about a deprecated default constructor in the C++ binding reported by GCC 9.0. (René Schwaiger)

  • <>

<>

<>

Tools

  • kdb get -v now displays if the resulting value is a default-value defined by the metadata of the key. (Thomas Bretterbauer)

  • kdb cp now succeeds if the target-keys already have the same values as the source-keys. (Thomas Bretterbauer)

  • web-ui issue #2441 is fixed in form of a workaround (Josef Wechselauer)

  • kdb import does not fail anymore if executed more than once with the same target in the spec-namespace. (Thomas Bretterbauer)

  • kdb mount avoid adding sync if sync is already provided. (Markus Raab)

  • kdb list-tools now supports KDB_EXEC_PATH environment variables that contain spaces. (René Schwaiger)

  • gen-gpg-testkey is added to the default tools list (see #2668).(Peter Nirschl)

  • <>

  • <>

Code generation

kdb gen is now no longer an external tool implemented via python, but rather a first class command of the kdb tool. For now it only supports code generation for use with the highlevel API. To try it just run kdb gen elektra <parentKey> <outputName>, where <parentKey> is the parent key of the specification to use and <outputName> is some prefix for the output files. If you don't have your specification mounted, use kdb gen -F <plugin>:<file> elektra <parentKey> <outputName> to load it from <file> using plugin <plugin>.

. (Klemens Böswirth)

Scripts

  • The reformat-source script now also formats tests/shell/include_common.sh.in. Additionally it ensures that the file is 1000 lines long, so that line numbers of files using it are easier to read. (Klemens Böswirth)

  • The clang-format wrapper script now also checks the supported maximum version of Clang-Format. (René Schwaiger)

  • The script reformat-shfmt now also reformats shell support files (*.in) in the scripts folder. (René Schwaiger)

  • The reformat-* scripts now allow you to specify a list of files that should be formatted. Only files actual suitable for the reformat script, will reformat. So e.g. calling reformat-cmake src/include/kdbprivate.h doesn't change any files. (Klemens Böswirth)

  • The script scripts/reformat-all is a new convenience script that calls all other reformat-* scripts. (Klemens Böswirth)

  • The script scripts/pre-commit-check-formatting can be used as a pre-commit hook, to ensure files are formatted before committing. (Klemens Böswirth)

  • The link checker now prints broken links to the standard error output. (René Schwaiger)

  • We added a script, called benchmark-yaml that compares the run-time of the YAML plugins:

    for a certain input file with hyperfine. (René Schwaiger)

Benchmarks

  • The benchmarking tool benchmark_plugingetset now also supports only executing the get method for the specified plugin. For example, to convert the data stored in the file benchmarks/data/yaypeg.test.in with the YAy PEG plugin to a key set you can now use the following command:

    benchmark_plugingetset benchmarks/data user yaypeg get

    . (René Schwaiger)

Documentation

Style

Tutorials

Spelling Fixes

  • Write Elektra with capital letter in cascading tutorial. (Vlad - Ioan Balan)
  • Add typo fix to the hello-elektra tutorial. (Dmytro Moiseiuk)
  • Add typo fix to the Java kdb tutorial. (Dominik Hofmann)
  • Fixed capitalization of the initial letter in Readme. (Miruna Orsa)
  • Improved readability in README. (Philipp Gackstatter)
  • We fixed some spelling mistakes in the documentation. (René Schwaiger)

Other

  • The Markdown Link Converter now uses the style

    filename:line:0

    instead of

    filename|line col 0|

    to show the location data for broken links. This is also the same style that Clang and GCC use when they display location information for compiler errors. This update has the advantage, that certain tools such as TextMate are able to convert the location data, providing additional features, such as clickable links to the error source. (René Schwaiger)

  • The Markdown Link Converter uses the index 1 for the first line number instead of 0. This update fixes an off-by-one-error, when the user tries to use the error location data printed by the tool in a text editor. (René Schwaiger)

  • We added a badge for LGTM to the main ReadMe file. (René Schwaiger)

  • Added LCDproc and Cassandra specification examples. These examples provide a good guideline for writing specifications for configurations. (Michael Zronek)

  • Added a new error message format concept to be implemented soon. (Michael Zronek)

  • Added a new error concept for error codes to be implemented soon. (Michael Zronek)

  • Added error categorization guidelines to be used with the error concept. (Michael Zronek)

  • Drastically improved the error message format. For more information look here. (Michael Zronek)

  • We fixed the format specifiers in the “Hello, Elektra” example. (René Schwaiger)

  • Expanded the Python Tutorial to cover installation under Alpine Linux. (Philipp Gackstatter)

  • We wrote a tutorial which is intended to help newcomers contributing to libelektra. (Thomas Bretterbauer)

Tests

  • We now test the Directory Value Plugin with additional test data. (René Schwaiger)

  • The variables:

    • SPEC_FOLDER
    • SYSTEM_FOLDER
    • USER_FOLDER

    in the inclusion file for shell test were set incorrectly, if the repository path contained space characters. (René Schwaiger)

  • The CFramework now also compares the names of meta keys. (René Schwaiger)

  • The release notes check does not report an illegal number anymore, if the release notes were not updated at all. (René Schwaiger)

  • We added a test for the keyhelper-class which checks if rebasePath calculates the new path for cascading target-keys correctly. (Thomas Bretterbauer)

  • Enable MSR for the crypto and fcrypt tutorial (#1981).(Peter Nirschl)

  • We fixed the Markdown Shell Recorder test for the command kdb get. (René Schwaiger)

Source Code Checks

  • The formatting instructions printed by check_formatting now also work correctly, if

    • the diff output does not start with the test number added by CTest, and
    • you use a non-POSIX shell such as fish

    . (René Schwaiger)

  • We now check the source code of the repository with LGTM. (René Schwaiger)

  • We fixed various warnings about

    • missing or duplicated include guards,
    • undefined behavior,
    • incorrect format specifiers,
    • unnecessary statements,
    • short names for global variables, and
    • empty if-statements

    reported by LGTM. (René Schwaiger)

Build

CMake

  • The build system now rebuilds the JNA binding with Maven, if you change any of the Java source files of the binding. (René Schwaiger)
  • <>
  • <>

Docker

Alpine Linux

Debian

  • We now use the default JDK on Debian sid, since the package openjdk-8-jdk is not available in the official unstable repositories anymore. (René Schwaiger)

  • We added

    to the image for Debian sid. (René Schwaiger)

Other Updates

Vagrant

Infrastructure

Cirrus

  • We added the build job 🔗 Check, which checks the documentation for broken links. (René Schwaiger)
  • <>
  • <>

Jenkins

  • We disabled the tests:

    • testmod_crypto_botan,
    • testmod_crypto_openssl,
    • testmod_dbus,
    • testmod_dbusrecv,
    • testmod_fcrypt,
    • testmod_gpgme, and
    • testmod_zeromqsend

    , since they are known to fail in high load scenarios. (René Schwaiger)

  • We increased the automatic timeout for jobs that show no activity from 5 to 10 minutes. (René Schwaiger)

  • We improved the exclusion patterns for the Coveralls coverage analysis. (René Schwaiger)

Travis

Website

The website is generated from the repository, so all information about plugins, bindings and tools are always up to date. Furthermore, we changed:

  • Added github build status badges to website (hesirui)
  • We updated part of a test for the snippet converter. (René Schwaiger)
  • <>

Outlook

We are currently working on following topics:

  • <>
  • <>
  • <>

Statistics

Following authors made this release possible:

<<scripts/git-release-stats 0.8.<<VERSION>>>>

Join the Initiative!

We welcome new contributors! Read here about how to get started.

As first step, you could give us feedback about these release notes. Contact us via our issue tracker.

Get the Release!

You can download the release from here or GitHub

The hashsums are:

<<scripts/generate-hashsums>>

The release tarball is also available signed by Markus Raab using GnuPG from here or on GitHub

Already built API-Docu can be found here or on GitHub.

Stay tuned!

Subscribe to the RSS feed to always get the release notifications.

If you also want to participate, or for any questions and comments please contact us via our issue tracker on GitHub.

Permalink to this NEWS entry

For more information, see https://libelektra.org

Best regards, Elektra Initiative