implement kdb validate

[markus2330]

Write the tool kdb validate <key> similar to kdb set but simply setting all the keys exactly the same as they were. The goal would be to validate the current files with their specification.

For example:
kdb validate system:/mykey

would get all keys below system:/mykey, make them dirty (e.g. by setting to a different value and then again to the original value) and then write back all keys below system:/mykey.

Note: plugin-check -f without arguments already implements something like this (except it does not make everything dirty and is kind of a misfeature to have it in this tool, the feature should be removed from plugin-check.

[flo91]

Jakob and I selected this issue for our FLOSS project, so here’s our proposal according to the assignment description. The rest of the assignment (research of similar initiatives, comparison with other issue trackers) can be found in our submitted document in TUWEL.

The project is about implementing a new validation tool for subsets of the key database. It should be integrated in the kdb-command of Elektra and called by: kdb validate <key>
With that validation tool it should be possible to validate the current files with their specification. When the tool is called, all keys below the key given as an argument are set to a value different from their current value and afterwards back to their old value.
After implementing the new command and its functionality, we’re also going to remove the possibility to do checks on the key database with the plugin-check tool. The current usage-info for the plugin-check tool is as follows:

Usage: bin/kdb plugin-check [<name>]
Do some basic checks on a plugin.
If no arguments are given checks on key database
are done instead. Use -f to also do a write test
(might change configuration files!)

Now the functionality that’s described in the part starting with "If no arguments are given..." is going to be removed, because the new kdb validate <key> command should be used instead for that task.
The plugin-check tool should get changed to only accept calls with a plugin name as argument, so a call without an argument won’t be allowed any more and the parameter -f won’t have any effect. The new usage-info would look like this:

Usage: bin/kdb plugin-check <name>
Do some basic checks on a plugin.
The plugin to check is given by its name as an argument.
A call without arguments is no longer supported! 
The checks on the key database are now handled by the 
command: kdb validate <key>

We still have to decide whether we should add the last part (starting with "A call without arguments...") to the new usage message of the plugin-check command to help users who notice the removed functionality.

Furthermore, new unit tests that check the behaviour and results of the kdb validate <key> command should be implemented.
If any existing unit tests use the plugin-check tool without arguments, that tests have to be modified to fit the new situation.

Another task is to write new documentation for the kdb validate <key> tool, check all current documentation for descriptions of the plugin-check tool and change the documentation to represent the new behaviour of that command.

An additional part of the project is to check, if any build scripts (e.g. for executing tests) must be modified to include the new tool and respect changes of the plugin-check tool.

The kdb-tool is written in C++ and we intend to also implement the new validation-tool in that programming language. To accomplish this, we plan to add a new class named validate (validate.hpp, validate.cpp) to /src/tools/kdb/.
Alternatively, it’s also an option to implement the validation-functionality as a new separate tool and integrate it in Elektra as described in /src/tools/README.md.

For this project, we’ll use this GitHub issue tracker of the libelektra-repository which belongs to the Elektra-initiative.

[max-thoma]

[FLOSS P1]
(This review is also on TUWEL)

Summarize in your own words which FLOSS project the document proposes.

The project aims to implement a validation function into the kdb command line utility, which will deprecate ‘plugin-check -f’. The new command will have a more robust approach on validating.

Are all sentences short and clear?

Yes, the proposal is written in short sentences that are easy to comprehend.

How would you define the problem and the scope more clearly?

I think that the scope of the problem is already defined clearly. It would be very hard to improve it. The authors have broken down the issues in smaller sub-goals and tasks that will allow them to monitor their progress very efficiently.

How would you explain the implementation sketch more clearly?

Their implementation sketch is already very detailed and clear. They only thing that they could have had done, is taking a look beforehand how many and which unit tests use the deprecated ‘plugin-check’ command. But I do not think, that this was necessary for this proposal.

Other than that, I would argue that the implementation sketch is very well thought through.

Is the document consistent with its terms?

There were no perceivable inconsistencies in the proposal.

Which other initiatives did you find which are similar?

As it is already mentioned in the issue, there exist various configuration management systems/libraries, but none of them has the same vision and feature set as elektra. While searching for similar libraries to elektra, I only stumbled across configuration management systems which are either very domain or language specific.

Which other issue trackers might be more suitable?

I think that their choice of using the GitHub issue tracker is excellent, since this is the preferred way of the initiative. For their personal sub-tasks, they might want to use a more task-oriented tracker such as Trello.

Summary

This is a very solid and well put together proposal. I only had very small critic points. I am convinced that the authors will be successful and wish them good luck for their project!

[markus2330]

Thank you for writing the proposal!

Please also note that #4059 is tightly related to kdb validate. So you also need to check for warnings and let kdb validate fail on any validation warnings. It is important that you have real-world verified markdown-tutorial tests (will be explained in L05), that demonstrates that invalid configs actually let kdb validate fail.

-f is also useful for kdb validate: with it you can enable to do kdbSet even though kdbGet already failed (with a warning). Other than than the warning-check (which should be in libtools, as probably others want to check for warnings, too) should be very straightforward and simple to implement kdb validate. For the warning check there is already one implementation in the HL-API: src/libs/highlevel/elektra_error.c Please also add tests for the C++ warning API in libtools. It is probably a good idea to first start with drafting an API, so that you don't need to redo the implementation if you make errors in designing the C++ API.