Dependency and compatibility info in addon template

[bilderbuchi]

I think the addon template should also have dependency and compatibility info included in some file (xml?) or other automatedly processable form (special strings in the README?). This was discussed a couple of times already, but the discussion never came to a conclusion. Maybe now is a good time to do this.

What info should be included?
How should it be included?
How do we allow/account for future features like automated addon download by PG (openframeworks/openFrameworks#1233)?

@obviousjim @atduskgreg @ofTheo @ofZach @arturoc: Thoughts?

[obviousjim]

there was some talk about using homebrew for this, but I kept backing away
because it was such a beast. We don't really need
configuration/installation -- we just need files to get downloaded to the
right place.

I propose something like this:

the readme can have key/value pairs that ofxaddons will recognize and add
tags to.

dependency: https://github.com/YCAMInterlab/ofxTimeline
dependency: https://github.com/obviousjim/ofxGameCamera
...

Then a download script will go fetch the rest of the required addons.
There may be a problem when 2 addons require different forks of the same
addon... but that is probably an edge case

Maybe you can also specify target platforms
platform: iOS
platform: OS X
platform: Linux

This developers can state what they are going for.

What do you think @atduskgreg?

On Tue, Jul 24, 2012 at 12:45 AM, Christoph Buchner <
reply@reply.github.com

wrote:

I think the addon template should also have dependency and compatibility
info included in some file (xml?) or other automatedly processable form
(special strings in the README?). This was discussed a couple of times
already, but the discussion never came to a conclusion. Maybe now is a good
time to do this.

What info should be included?
How should it be included?
How do we allow/account for future features like automated addon download
by PG (openframeworks/openFrameworks#1233)?

@obviousjim @atduskgreg @ofTheo @ofZach @arturoc: Thoughts?

---

Reply to this email directly or view it on GitHub:
#4

• James

[arturoc]

I want to investigate some file format that replaces the current
libsorder.make +

• different search paths than the usual ones
• additional libraries ( in the system, probably only useful for linux)
• dependencies with other addons
• system packages that need to be installed ( linux only )
• additional code to be included not in src

and probably others, something similar to the current install.xml but
optional and plain text so it can be parsed easily from Makefiles. I
want to have this for the next release.

this file can be parsed by ofxaddons to look for dependencies and also
by the PG or any other tool for downloading online addons with their
dependencies

El 23/07/12 22:54, James George escribió:

there was some talk about using homebrew for this, but I kept backing away
because it was such a beast. We don't really need
configuration/installation -- we just need files to get downloaded to the
right place.

I propose something like this:

the readme can have key/value pairs that ofxaddons will recognize and add
tags to.

dependency: https://github.com/YCAMInterlab/ofxTimeline
dependency: https://github.com/obviousjim/ofxGameCamera
...

Then a download script will go fetch the rest of the required addons.
There may be a problem when 2 addons require different forks of the same
addon... but that is probably an edge case

Maybe you can also specify target platforms
platform: iOS
platform: OS X
platform: Linux

This developers can state what they are going for.

What do you think @atduskgreg?

On Tue, Jul 24, 2012 at 12:45 AM, Christoph Buchner <
reply@reply.github.com

wrote:

I think the addon template should also have dependency and compatibility
info included in some file (xml?) or other automatedly processable form
(special strings in the README?). This was discussed a couple of times
already, but the discussion never came to a conclusion. Maybe now is a good
time to do this.

What info should be included?
How should it be included?
How do we allow/account for future features like automated addon download
by PG (openframeworks/openFrameworks#1233)?

@obviousjim @atduskgreg @ofTheo @ofZach @arturoc: Thoughts?

---

Reply to this email directly or view it on GitHub:
#4

[bilderbuchi]

The advantage I see with @obviousjim's approach is that this info being in/parsed from the README, we won't have to duplicate it somewhere else, so that it is readily available for both humans and computers. Also, I think it would be easier for addon maintainers to add this to a README than to construct an xml/json/whatever file, and we want to make it as easy as possible, right? or would your file also be just key:value pairs, arturo?
What tag set would you propose, @obviousjim? dependencies, target platforms, anything else? I suggest also including OF version compatibility/"testedness" - this could tie in nicely with the ofxaddons "freshness" indicator you are planning.

Arturo's approach would be much more powerful of course, in that we can also store more complicated, "internal", info.

@arturoc: by next release, you mean 0073, right? 'cause 0072 is way late, already...
also @arturoc, what's the current status of the install.xml? Do we use it? Will we continue to use it? Where can I find info regarding the expected structure/content (to include in the template)?

The beauty of ofxaddons is, when addons get published/updated (btw, do you crawl all the addons regularly?), we can check if the README or Arturo's file are "valid"/parse correctly, and if not, automatically open an issue via the GH API! Maybe this could later even be extended to testing compliance with the addon template structure...

[benben]

I would recommend to look on other excellent dependency tools like bundler (ruby) or npm (node.js) which do dependency management exactly the same way we want to do.

npm example written for an addon:

{
  "name": "ofxMyCoolAddon",
  "description": "a very cool addon which can do a lot of cool things",
  "author": "Cool addon author <me@example.com>",
  "dependencies": {
    "ofxFenster": ">= 1.2.0", // source can be omitted, because it is the same on ofxaddons
    "ofxSpecialAddon":  "http://some/special/source/path" // can be local, git or http path
  },
  "openFrameworks": "0071",
  "tags": ["working on linux", "experimental", "needs fix on windows"]
}

I think the node management is a little bit smarter, because its pure json and we don't need any further interpreter.

/edit/

If we say every addon needs a package.json or something like that, we can even use it to add tags, we talked about on the ml like "working on linux", "experimental", etc. (I added this to the example above)

ofxaddons app can then easily parse this file or file a issue if an addon doesn't have one or send an automated pull request with a template of this file :)

/edit2/

another advantage on relying on some standardized format is the fact that we are open to further enhancements in some directions because we can use already existing parsers for the dependency management in every possible language.

[obviousjim]

Where would this file live?

On Tue, Jul 24, 2012 at 4:41 PM, Benjamin Knofe <
reply@reply.github.com

wrote:

I would recommend to look on other excellent dependency tools like bundler
(ruby) or npm (node.js) which do dependency management exactly the same way
we want to do.

npm example written for an addon:

{
  "name": "ofxMyCoolAddon",
  "description": "a very cool addon which can do a lot of cool things",
  "author": "Cool addon author <me@example.com>",
  "dependencies": {
    "ofxFenster": ">= 1.2.0", # source can be omitted, because it is the
same on ofxaddons
    "ofxSpecialAddon":  "http://some/special/source/path" # can be local,
git or http path
  },
  "openFrameworks": "0071"
}

I think the node management is a little bit smarter, because its pure json
and we don't need any further interpreter.

---

Reply to this email directly or view it on GitHub:
#4 (comment)

• James

[bilderbuchi]

I'd say in the addon root directory.

[obviousjim]

I don't really like it honestly. I know it's nice to leverage existing
technology - but it feels like overkill.

the regular expression to parse something that is on one line and contains
one ":" is certainly not a bad wheel to re invent

and the human readable factor + we already have README parsing in ofxAddons
is a +2 to keeping it simple and straight forward.

that's my 2円 neway

On Tue, Jul 24, 2012 at 5:45 PM, Christoph Buchner <
reply@reply.github.com

wrote:

I'd say in the addon root directory.

---

Reply to this email directly or view it on GitHub:
#4 (comment)

• James

[benben]

+1 for root directory.

@obviousjim Beside how the file is formatted, I think its no overkill to add more (standardized) information to it, because there is need for more meta-information and personally I don't like the proposal for adding marker like snippets cluttering the names/descriptions/issues on github (like the proposal mentioned on the ML). I think it makes more sense to put all this in a file. Also I think if there will come other features, we could add it to the file. Do you agree on storing everything meta in a file and you just don't like the formatting?

[bilderbuchi]

I think what James is driving at is that it should be sufficient to keep it in the README, with a simple : as a marker, instead of some elaborately structured file.
This would have the advantage of also being immediately readable and available to the user at the first point-of-entry, i.e. the README. Additionally, keeping info solely in the README would avoid duplication (and maintenance mistakes) of e.g. having the version number or dependencies in several files. So in that regard I tend to agree.

However, the simple scheme already gets more complicated if we get more complicated info (in the future), e.g. multiple dependencies as already above, or multiple attributes for one thing (dependency-version, -url(optional), -name, -minVersion,...), and we then might as well stick to an already well-established and proven syntax.

Maybe a middle ground is to have a metadata section at the end of the README, with something similar to what ben posted above in it?

[ofTheo]

*** "I want to investigate some file format that replaces the current
libsorder.make +

• different search paths than the usual ones
• additional libraries ( in the system, probably only useful for linux)" ***

@arturoc isn't that what install.xml is? ;)
why not just expand that?

[benben]

how do we mark the seperation of "normal readme" and "meta data in readme". do we agree on a special marker or something like that? From my side I'm fine with adding it to the end of the README but I'm currently unshure how we make this reliable to seperate from normal readme content.

[bilderbuchi]

could be: "line starts with one of a list of predefined keywords, then :", or something like that?

[benben]

ok I put everything in a gist to discuss further: https://gist.github.com/3197172
So everyone can see MD and raw data and can fork/edit easily. I had to put an empty line between every entry, that MD renders it right.

What I not included for now is @arturoc data, because I don't know how to include it. Especially needed packages on linux, because they are named differently on every platform. I think we need more discussion on this. Maybe @arturoc can add the info as he like and we can see if everyone is happy with it.

[benben]

What I forgot: The syntax is now a valid YAML syntax, which a) renders good in MD and is b) easily parsable.

[bilderbuchi]

hm, that meta.md file looks like a good approach. I think I could use that also to store the meta information in https://github.com/bilderbuchi/ofStateManager, although I used json there. I'm not set on anything, though.