finalize infos/status

[markus2330]

add in CONTRACT.ini

• [ ] finish #4758
• [ ] example .. plugin is only an example how plugins should be (doc+template), see #1012
• [ ] remove nodep and use dependencies/ instead

also add automatic check

• [ ] documentation
• [ ] environment

check features of plugins manually

• [ ] read
• [ ] write
• [ ] spec//
• [ ] preserves/order
• [ ] preserves/comment
• [ ] preserves/comment/empty
• [ ] preserves/indentation
• [ ] limited
• [ ] arbitrary/keyset
• [ ] arbitrary/metadata
• [ ] directory/value
• [ ] directory/holes
• [ ] type
• [ ] array
• [ ] format/array
• [ ] format/hierarchy
• [ ] format/type
• [ ] format/human/read
• [ ] format/human/write

[markus2330]

Maybe we also can find automated ways here?

[markus2330]

@Namoshek Would nocomments and noorder be useful for the web frontend?

[Namoshek]

Are not (almost) all plugins noorder? I thought during import, when keys are put into a keyset, they get automatically sorted in alphabetical order?

I think they are not really useful/necessary, because on the one hand, the fact that comments are missing is immediatly visible and on the other hand, it should be clear that not all formats do even support comments (e.g. json). So I wouldn't really use this information.

But you brought the idea up to me to just pass all statuses through the REST API to the user. Then additions to the plugin information would only require a change in the frontend in future, not to the API description and the backend anymore.

[markus2330]

Are not (almost) all plugins noorder? I thought during import, when keys are put into a keyset, they get automatically sorted in alphabetical order?

Yes, most plugins are noorder and nocomment. Exceptions are hosts and ini.

not all formats do even support comments (e.g. json)

Yes, that is similar to readonly/writeonly/limited: sometimes only implementation is missing, sometimes it is a wanted limitation.

But you brought the idea up to me to just pass all statuses through the REST API to the user. Then additions to the plugin information would only require a change in the frontend in future, not to the API description and the backend anymore.

Good idea!

[KurtMi]

Should I add those?

[markus2330]

Could you first investigate which of ìnfos/status`(also of those we already have) we can determine automatically easily (within your tool)?

[KurtMi]

I investigated a bit and determined the following tags as automatic checkable. unittest look for testmod_PLUGIN* preset nodep check infos/recommends or infos/needs ? readonly see in code if only elektraPLUGINGet is there (maybe tricky) writeonly see in code if only elektraPLUGINSet is there (maybe tricky) nodoc only contract in README.md

Do you think this is possible and right? Are there more?

[markus2330]

Hello, thanks for the investigation!

unittest look for testmod_PLUGIN* preset

Yes, but ADD_TEST or add_plugintest in the CMakeLists.txt should be more robust.

nodep check infos/recommends or infos/needs ?

Seems like the docu was misleading, I updated it. It is actually about presence of LINK_LIBRARIES or find_package or find_library. The tagging should be correct at the moment, so you can easily verify if you missed something.

readonly/writeonly

I do not think that this is possible to detect. Especially in elektraPLUGINGet there is always the returning of the contract.

nodoc only contract in README.md

I think we can be more strict: if it has a length similar to template and no code examples we give it nodoc.

Are there more?

• configurable: if the plugin uses elektraPluginGetConfig
• memleak: if MEMLEAK is present in CMakeLists.txt
• noabi .. plugin depends on some internal information of Elektra (kdbprivate.h)

I updated the top post with this check list.

[KurtMi]

#1069 contains:

• configurable
• memleak
• unittest
• nodep
• nodoc

I have some issues with the nodoc, its hard to say what is an example and what not.

[markus2330]

Thank you, nicely done! Can you please tick it in the above post?

nodoc

Simply count the lines of source within markdown.

Can you also check kdbprivate.h?

[markus2330]

Do you think it is also possible to grep getenv from the source and add all environment variables being used by a plugin? (similar to grepping for kdbprivate.h)

[markus2330]

@kodebach wrote:

If anything, I would have a status humanreadable and refuse to export to a tty stdout, if the format is not human readable.

Yes, I like that idea that we somehow better tag the usability of plugins. Further ideas are welcomed.

[markus2330]

I added "(no) open bugs over a release (maybe this is already said by "maintained"?)"

[stale[bot]]

I mark this issue stale as it did not have any activity for one year. I'll close it in two weeks if no further activity occurs. If you want it to be alive again, ping the issue by writing a message here or create a new issue with the remainder of this issue. Thank you for your contributions :sparkling_heart:

[markus2330]

would be nice to see a bit refactoring of infos/status for 1.0.

[markus2330]

I have to admit that I am myself confused what the difference between experimental, unfinished and concept is. So also removal of some infos/status seems to be necessary, too.

[kodebach]

I think that a big mistake with infos/status is the rating behind it. It is very much not obvious that this even exists and it makes properly choosing infos/status flags very hard. I suspect if a PR would add a base32 plugin for binary data, without looking up the rating or just trying, nobody would know from looking at infos/status whether it would rate higher than base64 or not.

AFAIK this rating is only used to choose which plugin to use if e.g. binary is requested instead of e.g. base64. I think infos/status should be purely to indicate development/maintenance status. To choose e.g. a default binary plugin, there should be separate manually defined list of default plugins for all the "pseudo-plugins" (binary, storage, etc). We could even put this list into the KDB and allow users to choose their own defaults.

[kodebach]

As a sidenote, if feasible, we might also want to investigate converting all the stuff at the beginning of the plugin README into something closer to standard YAML front matter. (The infos key can be auto-generated from the plugin name, so the rest doesn't have to use the infos/ prefix).

We should also leave out the empty fields, unless the absence of this field is somehow unusual (e.g. empty infos/status because the status is unknown).

Using YAML front matter would result in nicer rendering on Github. For an example see: https://github.com/jonschlinkert/gray-matter/blob/master/examples/fixtures/coffee.md (click the "Raw" Button to see the unformatted markdown)

[markus2330]

Do you have an example where the rating fails for you? (Picks an unwanted plugin.) Obviously it is not a good idea that a plugin is called exactly as its format, as then it might get surprising. But #3491 should fix that.

I would not leave out empty fields, this only makes complications. Or which would be the benefit you see?

Yes, improvements of the rendering of the READMEs are welcome. I did, however, already try a few ways (and I even considered YAML) and the current way was the best compromise between our website and GitHub. But if you find a better way (maybe also GitHub rendering changed), we can adopt it. When fixing this issue a bit reformatting should be no problem.

[kodebach]

Do you have an example where the rating fails for you?

Not right now, but I remember that for a time hexnumber was auto-selected for the type metadata instead of type.

It's not that it fails, it's more that is very magical. And not the good kind of magic, but black magic where a new user has no idea how or why a plugin was selected.

I would not leave out empty fields, this only makes complications. Or which would be the benefit you see?

The infos/features proposed in #3504 would only apply to storage plugins, so it would be unnecessary or even confusing to have it in other plugins. I was mainly thinking about such cases. infos/metadata, infos/needs and infos/recommends could also be left out if empty, but they could just as well be kept for uniformity.

Yes, improvements of the rendering of the READMEs are welcome. I did, however, already try a few ways (and I even considered YAML) and the current way was the best compromise between our website and GitHub. But if you find a better way (maybe also GitHub rendering changed), we can adopt it. When fixing this issue a bit reformatting should be no problem.

Not sure, what the website does right now, but it uses any form of standard Javascript markdown parser, handling standard YAML frontmatter should be pretty simple. (The example above is from a JS library for just that purpose)

The problem with proper YAML frontmatter would, be that we need to also handle it during the build process. That might be a bit more complicated, unless we use a very limited YAML subset.

[markus2330]

I remember that for a time hexnumber was auto-selected for the type metadata instead of type.

Yes, this is same problem as with ini: there is the implicit assumption that if a plugin is called like the provider or meta-data it must be the one-and-only. Otherwise, it gets very confusing.

I was mainly thinking about such cases.

Yes, if it only exists for some types of plugins. infos/features might be extended to other types, though.

handling standard YAML frontmatter should be pretty simple

The problem is to make it look nice. Tables are more difficult.

[kodebach]

infos/features might be extended to other types, though.

I think we should use separate keys, e.g. infos/features/storage and infos/features/type. Otherwise will just end-up with the same mess as infos/status, especially if we start using a single flag for two different meanings.

The problem is to make it look nice. Tables are more difficult.

You underestimate the Javascript community... There are 1000s of npm packages to convert JSON to HTML (YAML front matter is normally parsed into JSON)

For example: https://marianoguerra.github.io/json.human.js/

Since we are limited by our build system anyway, I think even a hand written solution wouldn't be too hard. (I have however zero knowledge of AngularJS so I certainly can't build something for our website)

[markus2330]

I think we should use separate keys, e.g. infos/features/storage and infos/features/type.

I agree, very good idea. :+1:

so I certainly build something for our website

I hope you did not want to write some "not" somewhere :sparkle:

[stale[bot]]

I mark this issue stale as it did not have any activity for one year. I'll close it in two weeks if no further activity occurs. If you want it to be alive again, ping the issue by writing a message here or create a new issue with the remainder of this issue. Thank you for your contributions :sparkling_heart:

[kodebach]

see also #3504

[github-actions[bot]]

I mark this stale as it did not have any activity for one year. I'll close it in two weeks if no further activity occurs. If you want it to be alive again, ping by writing a message here or create a new issue with the remainder of this issue. Thank you for your contributions :sparkling_heart:

[github-actions[bot]]

I closed this now because it has been inactive for more than one year. If I closed it by mistake, please do not hesitate to reopen it or create a new issue with the remainder of this issue. Thank you for your contributions :sparkling_heart: