Plugin Status documentation

[atmaxinger]

Is there any documentation/overview of the plugin info/status field? When one is creating a new plugin it automatically defaults to

- infos/status = recommended productive maintained reviewed conformant compatible coverage specific unittest shelltest tested nodep libc configurable final preview memleak experimental difficult unfinished old nodoc concept orphan obsolete discouraged -1000000

As a plugin author, it is very hard to determine which ones are appropriate for the plugin and which ones are not.

[flo91]

In /doc/CONTRACT.ini is a description of the infos/status field:

libelektra/doc/CONTRACT.ini

Lines 285 to 330 in 6fe5335

	[infos/status]
	type = vector<long enum>
	{"default", 64000}, ; will be added by the build system for KDB_DEFAULT_STORAGE and KDB_DEFAULT_RESOLVER
	{"recommended", 32000}, ; in case of doubt, use this plugin
	{"productive", 8000}, ; actively used in productive environments, not only by maintainer
	{"maintained", 4000}, ; actively used and fixed by maintainer (infos/author)
	{"reviewed", 4000}, ; actively reviewed on every change and not by maintainer
	{"conformant", 2000}, ; to indicate that e.g. a storage plugin fulfils all requirements of a storage plugin
	{"compatible", 2000}, ; to indicate it will be compatible with its later versions
	{"coverage", 2000}, ; unittests have full code coverage
	{"specific", 1000}, ; means that the plugin is non-portable in order to gain some specific advantages for the user
	; (i.e. in a positive sense specific/non-portable)
	{"unittest", 1000}, ; substantial plugin unittests (testmod)
	{"shelltest", 1000}, ; substantial unittests with shell
	{"tested", 500}, ; extensively manually tested on every change
	{"nodep", 250}, ; no external library dependencies, except the languages core deps, e.g. libstdc++ and other plugins in `needs`
	{"libc", 250}, ; uses libc only, no deps of other language’s run-times, e.g., libstdc++
	{"configurable", 50}, ; options available to modify behavior
	{"final", 50}, ; no further extensions, configure options or features are desirable
	{"global", 1}, ; suitable as global plugin
	{"readonly", 0}, ; can only read data from files (only kdbGet implemented)
	{"writeonly", 0}, ; can only write data to files (only kdbSet implemented)
	{"preview", -50}, ; plugin in technical preview state
	{"memleak", -250}, ; memleak in plugin or one of the libraries the plugin uses
	{"experimental", -500}, ; not much tested, plugin is in early stage, disabled in CMake by default
	{"difficult", -500}, ; the plugin is (unnecessarily) difficult to use
	{"limited", -750}, ; cannot represent arbitrary data (i.e. very specific format)
	{"unfinished", -1000}, ; important functionality still missing
	{"old", -1000}, ; code base is old and should be refactored/improved
	{"nodoc", -1000}, ; documentation is minimal
	{"concept", -2000}, ; the plugin only exists to demonstrate something
	{"orphan", -4000}, ; author does not respond and also otherwise not much knowledge about plugin is present
	{"obsolete", -4000}, ; another plugin fulfils a similar functionality in a better way
	{"discouraged", -32000}, ; only use the plugin if you really know what you are doing
	status = implemented
	usedby = plugin spec binding
	description = Tags about how well-established and well-working a plugin is.
	Different status can be combined.
	Numerical values are allowed, too. Please argue in the infos/description why
	numerical values are used.
	When changing some value in the type, you need to copy the information to
	src/libs/tools/src/plugindatabase.cpp
	src/plugins/template/README.md

The CONTRACT.ini file is already mentioned in the README.md of the template plugin:

libelektra/src/plugins/template/README.md

Lines 36 to 37 in 6fe5335

	- make sure `status`, `placements`, and other clauses conform to
	descriptions in `doc/CONTRACT.ini`

[markus2330]

@flo91 thx for helping out! ❤️

In #666 there are some suggestions for improvements for infos/status. Better don't use the ones we want to remove there. (There is also a half-done PR for this #4758.)

Btw. in case of doubt it is better if we tag it negatively/experimental/..., it is very disadvantageous for Elektra or even FLOSS in general if someone expects it should work and it does not.

In doc/tutorials/xfconf.md we also should add a disclaimer (for me some parts still did not work).