Metadata: One Standard to Rule Them All

[mnesarco]

One very important thing is that a package can contain many things, there is no such thing like a package type, because there can be anything inside the pakage. It is very easy so have many workbenches inside the same package currently. And there are some workbenches that also provide macros. And some packages does not contain Workbenches neither macros, just a set of python classes/functions usable by other extensions.

The package is a container of extensions. There must be some metadata about the package itself and metadata of each extension included.

About dependencies, each extension can declare its dependencies, but maybe it is better to keep only one global dependencies section as you already have.

dependencies/versioning is a very hard topic. FreeCAD does not check/validate/enforce dependencies of extensions currently, so i suppose that section is informative to the user but not enforced.

[mnesarco]

1. Repository URL (git)

Is your suggestion that this be required? It's an allowed url value right now.

Yes. There must be a source url from where the package can be installed/updated. If that is your intention with the current url field, it is ok.

2. Readme URL
3. Readme Format (html, markdown, wiki, ...)

Maybe add "readme", "documentation" and/or "help" as a possible URL categories? What is the purpose of the "format" entry? Is the intention to allow inline display of the URL contents?

Have you tried ExtMan? the user can search for extensions and see the readme. some extensions have markdown, some others wiki, html...
One of the biggest advantages of having metadata is to gain discoverability, so the users can search and preview extensions. Once all extensions provide a proper manifest, we can create a public index of extensions where users can discover them.

screenshot_55.png (380.04 KiB) Viewed 2383 times

screenshot_57.png (455.04 KiB) Viewed 2383 times

4. Icon URL (Preferably a local path relative to the installation dir)

I'd probably make it a plain string path relative to the location of package.xml, that's how the rest of the local file references work in REP149.

Perfect.

5. tags (an array of string to classify the extension ie [architecture, mechanics, UI, 3DPrinting, ...])

Given that the format here is XML, would this be OK as a tag with multiples allowed, rather than a comma-separated list? e.g.

Code: Select all

<tag>architecture</tag>
<tag>mechanics</tag>
<tag>ui</tag>

rather than

Code: Select all

<tag>architecture, mechanics, UI</tag>

Of course, that was just a conceptual example.

[chennes]

3. Readme Format (html, markdown, wiki, ...)

Can we use the file extension to determine format?

[mnesarco]

3. Readme Format (html, markdown, wiki, ...)

Can we use the file extension to determine format?

Which is the extension of the format used in the freecad wiki? I suppose a mime type is more standard to determine the type of a digital content. But this is not critical as we dont have to support many formats. We can allow only two or three accepted readme formats and use the extension as discriminator.

[chennes]

OK, I've been poking around at the "<content>" element for a while today, and I'm waffling on it. On the one hand I understand that a package (potentially) contains many different sub-components. But the point of a package is that it should package them. So how much additional metadata is needed/desirable for the subcomponents? What is a package manager doing with the information about the subcomponents? That is, what are we going to use that metadata for?

I implemented two different extremes today: in the first, each subcomponent only provided a "name" element, so that we had a list of all the different kinds of sub-components and their names. In the other, I went to the other extreme, and allowed the entire Metadata data structure to be provided for each subcomponent. So name, license, description, etc. But when the time came to use it (for themes) I really didn't have a use for any of the sub-component metadata.

[mnesarco]

OK, I've been poking around at the "<content>" element for a while today, and I'm waffling on it. On the one hand I understand that a package (potentially) contains many different sub-components. But the point of a package is that it should package them. So how much additional metadata is needed/desirable for the subcomponents? What is a package manager doing with the information about the subcomponents? That is, what are we going to use that metadata for?

I implemented two different extremes today: in the first, each subcomponent only provided a "name" element, so that we had a list of all the different kinds of sub-components and their names. In the other, I went to the other extreme, and allowed the entire Metadata data structure to be provided for each subcomponent. So name, license, description, etc. But when the time came to use it (for themes) I really didn't have a use for any of the sub-component metadata.

Well, things like authors, license, version, repository, readme .. are obviously at the package level. The importan parts of the subcomponents are the info required for integration. For example, each workbench/macro has its own name, icon and description at least. In case of workbenches it would be great to know the fully qualified name of the class because currently it is the workbech who adds itself to FreeCAD, so FC doesn't know anything about the Workbench in advance. In ExtMam I had to parse __init__.py, init_gui.py and the legacy counterparts to extract such things and i can only do that once the extension is installed. Currently to inform freecad about the icon of a workbech in advance, it is required to commit the icon to the main FreeCAD repo which is ridiculous.

[chennes]

Excellent, thanks for the added information. So then the content section could look like:

Code: Select all

<content>
	<workbench>
		<name>Amazing Workbench</name>
		<description>An amazing workbench</description>
		<class>amazing_workbench</class>
		<icon>resources/amazing_icon.svg</icon>
	</workbench>
	<macro>
		<name>Great Macro</name>
		<description>A macro that does great things</description>
		<file>macros/great_macro.FCmacro</file>
		<icon>resources/great_icon.svg</icon>
	</macro>
	<theme>
		<name>Fantastic Theme</name>
		<description>A really fantastic-looking theme</description>
		<icon>resources/fantastic_icon.svg</icon>
		<screenshot>resources/fantastic_screenshot.png</screenshot>
		<file>fantastic_theme/fantastic_theme.FCtheme</file>
	</theme>
</content>

[mnesarco]

Excellent, thanks for the added information. So then the content section could look like:

Code: Select all

<content>
	<workbench>
		<name>Amazing Workbench</name>
		<description>An amazing workbench</description>
		<class>amazing_workbench</class>
		<icon>resources/amazing_icon.svg</icon>
	</workbench>
	<macro>
		<name>Great Macro</name>
		<description>A macro that does great things</description>
		<file>macros/great_macro.FCmacro</file>
		<icon>resources/great_icon.svg</icon>
	</macro>
	<theme>
		<name>Fantastic Theme</name>
		<description>A really fantastic-looking theme</description>
		<icon>resources/fantastic_icon.svg</icon>
		<screenshot>resources/fantastic_screenshot.png</screenshot>
		<file>fantastic_theme/fantastic_theme.FCtheme</file>
	</theme>
</content>

It looks very good. And we can improve it over time...

[Kunda1]

LGTM

[chennes]

mnesarco -- a question for you about how these "packages" work. The built-in Add-on manager really only supports installing into two relatively fixed locations:

Code: Select all

FreeCAD.getUserAppDataDir() + os.sep + "Mod"

and

Code: Select all

FreeCAD.getUserAppDataDir() + os.sep + "Macro"

Here there really isn't any notion that a package could contain either or both of these things, as the "Content" section of the new metadata format implies to me. Does your workbench use its own directory structure, or does it work within this one?

Ping