clarifying the meaning of "plugin", "package" etc.

[ltalirz]

This came out of a discussion with @csadorf

We currently don't use the term "plugin" consistently everywhere - it is used both to refer to

1. a python package (think aiida-quantumespresso), and
2. individual AiiDA extensions corresponding to an entry point (think aiida.calculations:quantumespresso.pw).

A look at the AiiDA registry and the descriptions of the various packages listed there makes clear that plugin developers think of 1. when they use the term.

I would therefore propose to find a more specific term for 2.

Possible candidates:

• Extension - e.g. the plugin registry summary would read: Calculations: 78 extensions in 33 plugins. Basically a synonym, which is not ideal
• Entry point - e.g. the plugin registry summary would read: Calculations: 78 entry points in 33 plugins. Accurate, but rather technical.
• Some AiiDA-themed fantasy word - like "score", "bar", "note" etc. Perhaps too confusing out of context.

Any suggestions @sphuber @giovannipizzi ?

[giovannipizzi]

I would be tempted to say we should call "plugin packages" the git repositories and "plugins" or "plugin entrypoints" the specific subclasses? Do you think nobody would comply with this? I think that it is more accurate however as a terminology, do you agree?

[ltalirz]

Re @giovannipizzi
I would be fine with using your proposal as the official line; but I think we would need to tolerate that developers will continue to call their contributions "AiiDA plugin for code X" - I think this is simply more natural than "AiiDA package for code X" (and shorter than "AiiDA plugin package for code X").
I think we would have to live with that bit of ambiguity.

However, we should make sure to be specific in the docs and in the API/cli. In particular, I think this means the command verdi plugin list should be called verdi entrypoint list instead.

The summary of the plugin registry would then read:
Calculations: 78 entry points in 33 packages

[sphuber]

I am also a strong proponent of trying to find clearer language because it causes misunderstanding very often. I also think that the packages will always be most naturally referred to as a "plugin". So I think we need a different one for the individual ones per entry point group. The downside of "entry point", while correct in a sense, also could just refer to the technical way that functionality in aiida-core can be extended. I am not sure "extension" is the correct name, but "entry point" is moreso the means than the thing itself. I think ultimately the most natural way of (a bit technically) phrasing it would be something like:

The aiida-quantumespresso plugin provides 50 "extensions" registered through entry points in the aiida.calculations entry point group

[sphuber]

In writing the section on the plugin system for the paper, I realized that I started using the following terminology, which I quite like:

• plugin: an extension of AiiDA core functionality
• entry point: the technical means with which a plugin is registered
• plugin package: a python package that bundles one or multiple plugins

Note that with these definitions, the word "plugin" by itself can refer to an extension of any type. Concrete plugins, like an entry point in the aiida.data entry point group, for example quantumespresso.force_constants, would then be referred to as a "data plugin". Similarly, quantumespresso.pw of the aiida.calculations group is a "calculation plugin", with the same from the aiida.parsers group being a "parser plugin".

[ltalirz]

In my view, what you are describing is pretty much the status quo; the problem being that "plugin package" is a bit long, so in practice people abbreviate it to plugin as well.

Anyhow, we could decide that the official term is "plugin package", change the name of the plugin registry to "AiiDA plugin package registry" and update our documentation to encourage people to use it.
Still, in this approach I believe people will continue talking about the "aiida quantumespresso plugin" (leaving out the package). Perhaps we just decide to live with that.

[sphuber]

In my view, what you are describing is pretty much the status quo; the problem being that "plugin package" is a bit long, so in practice people abbreviate it to plugin as well.

Hmm good point. Although as you say, if we at least use the term consistently in the code, documentation and all other communications, people might catch on at some point. And in any case, we will be able to make ourselves clear in our meaning

[ltalirz]

Just for completeness: there is another term, "distribution", which I guess was originally meant to distinguish between what python calls a package (= a folder with an __init__.py file) and what people put on PyPI.
However, for whatever reason, the python packaging guys have decided to mix it into "distribution package", and obviously PyPI stands for "python package index", not "python distribution index".
This is just to say that "distribution" is probably not the way to go.

@giovannipizzi So, do you agree with @sphuber's suggestion here?
I personally find "plugin package" a bit long, and suggest we simply abbreviate it to "package" where suitable.

I would then implement the following replacements:

• The "Plugin development" top-level docs section remains. We change the content of the section to focus on the generic aspects of adding a plugin first, and on packaging/distribution aspects later.
• "The aiida-quantumespresso plugin" => "The aiida-quantumespresso package"
• "AiiDA plugin registry" => AiiDA package registry (in analogy to the python package index)
• "Entry points provided by the plugin" => Plugins provided by the package.
• @aiidateam/plugin-developers remains

[giovannipizzi]

Seems reasonable, even if I'm a bit worried by the change of name of the plugin registry, I got used to it and it's already cited in a few places probably... But if we all agree we can do the move. We can try to vote at the next AiiDA meeting

[csadorf]

Honestly, I'm not sure that the name change of the AiiDA plugin registry is really necessary. It is true that the registry lists packages, but it also lists the plugins for each package.

[ltalirz]

Result of discussion at AiiDA meeting:

• we keep the name AiiDA plugin registry
• we will use the term plugin package in the documentation (where it is not too long)

Otherwise we stick to the proposal outlined above.