Symphony.

There has been a discussion about extension compatibility a while back. Now that this beautiful new site was launched are there any updates, if developers should include more details in their extensions’ about array?

How should we handle compatibility information on this site concerning different extension versions and the core releases?

This is something that’s already on our radar—the issue of multiple extension versions. I don’t think we’ve got a preferred solution yet.

Do GitHub tags not provide enough functionality? Or are you trying to not rely too heavily on services like GitHub?

This conversation never reached a conclusion, so is worth rekindling now.

The present way of documenting extension compatibility is one-dimensional. When you make an update, you mark what versions of Symphony the extension is compatible with. This hasn’t been a problem until now because most Symphony versions have been relatively backwards compatible, but with the pending 2.2 we’re updating extensions to the extent that they won’t work on pre-2.2 installs.

To this end, the current way of marking compatibility is great for the compatibility table but is otherwise insufficient.

I have updated most of my extensions now to be 2.2-ready. This means that the latest versions will not work with anything older than 2.2, but in the last week or so I’ve had a handful of developers try, and receive errors because of it. In short: we need a way to mark which version of an extension is compatible with each version of Symphony. It’s two dimensional, not one.

Nils has previously suggested embedding this information into an extension’s driver file. This works to an extent, but is still one dimensional.

        'compatibility' => array(
            '2.0.6' => true,
            '2.0.7' => true
        )

If I update my extension to work with only Symphony 2.2, do I mark it as incompatible with all previous Symphony versions? As a user scouting for extensions, I might think the extension only works with 2.2, whereas in reality an older version of the extension will work with an older version of Symphony.

Drupal attemps this and partially succeeds. Their support of Drupal 6 and 7 is going to be similar to our eventual need to support Symphony 2 and 3.

Mozilla take a similar approach in that they mark compatibility against each version of an extension:

Problem is, this adds administrative overhead to extension developers. I’ve tried to tackle this two dimensional problem by including a compatibility table in README files:

• https://github.com/nickdunn/order_entries
• https://github.com/nickdunn/publishfiltering

Useful to a user, but it’s still a burden for me to remember to update every time I update the extension. The benefit here is that this is human readable. Keeping this information tucked away in the extension driver file means it is machine readable only. And having it one-dimensional in the extension driver means I would need to go back through the history of the driver file looking at when the array changes to be compatible with my version, and figure out what tagged version that is.

So what can we do about this? Ultimately we need this information in both human and machine-readable formats. Human readable so someone can see the extension on Github, read the README file, and instantly know what is and isn’t compatible. Machine readable so that:

1. Symphony can warn users against installing extensions that may not work
2. The Symphony website can parse this and allow users to filter by compatibility, meaning developers don’t need to update manually here

There has been some chat about integration with Github, and how README files (or driver files, or configuration files) could be parsed from the repo and used directly on this site. This isn’t really what I’m looking to discuss here, but obviously anything we decide could be aligned towards making this a possibility in the future.

How should we handle two dimensional compatibility?

Just because I know me and just because I know other developers, it would be great to store this information in one place only. Having to update the readme and extension.driver.php is a source of mistakes.

That said: I like your table mapping version numbers to releases. Maybe it would be an idea to change this site’s behaviour from storing only one set off data for each extension to allow multiple entries per extension, e. g. by using SBL or SSM relations. This way we could have compatibility settings for each release. But this still won’t solve the issue that developers need to remember to update compatibility on this site. So I’d really like the Symphony site to parse the repositories on GitHub and extract the compatibility and display it nicely.

By the way, wouldn’t it be sufficient to link from the readme on GitHub to the extension page on this site? Seriously, those that don’t read you readme files will always ask why something is not working and will never read compatibility tables.

it would be great to store this information in one place only. Having to update the readme and extension.driver.php is a source of mistakes.

Agreed! A source of mistakes, and a pain in the bum. Problem is, the README file can be anything (plain text, Markdown, YAML etc.) and the extension.driver.php is PHP. The saviour in my eyes would be a new file, extension.meta.xml or something, which contains the extension’s about array as XML instead. This could be made fairly human readable, and would be machine-readable by Symphony and this website. But it’s a departure from established conventions.

I’ve experimented with parsing extension.driver.php directly from Github, and it works pretty well. So perhaps the about() array is the canonical place for this to live.

By the way, wouldn’t it be sufficient to link from the readme on GitHub to the extension page on this site

I don’t like putting much content into the “Description” field on this site as it’s somewhere else I have to update. I want the README file in the extension repository to be the canonical source of information about the extension. This is what goes into everyone’s local builds, so should contain everything in my opinion.

So this problem is really in two parts:

1. How do we handle documenting compatibility, in two dimensions rather than on?
2. How can we reduce the duplication of content between an extension repo?

those that don’t read you readme files will always ask why something is not working and will never read compatibility tables

Which is why this information needs to be in machine-readable form so that Symphony can warn against this when the developer installs the extension. But for conscientious users it’s also nice to have a human readable form. Perhaps machine-readable goes in the extension only, and is parsed into something human readable on this site, removing the need for my compatibility table in the README. I’m only using the table as a stopgap until we come up with a better idea.

I don’t like putting much content into the “Description” field on this site as it’s somewhere else I have to update.

Oh, I was thinking about parsing the repo for the needed information and display it automatically based on GitHub tags, so there would be no need for a manual update.

I like the way how WordPress rates it’s plugin compatibility. For example: http://wordpress.org/extend/plugins/contact-form-7/:

On the right each and every one who is logged in can select which WordPress version and which version of the plugin they are using and with that the system ‘magically’ calculates if the extension works, is broken or needs more votes to calculate a result.

I think something like this would be a huge plus for the extension compatibility table. Rate it on the experience of real users.

Attachments:

SS-2011-02-15_15.36.10.png

Agreed, Nils. But then we’re tied to Github. Is that a problem?

Symfony (our unfortunately named brethren) have two community sites which interact directly with Github:

• http://symfohub.com/
• http://symfony2bundles.org/

The implementations are poor and neither cater for this two-dimensional compatibility for versioning. I like the concept though — you sign in to Symfohub using your Github account (OAuth) and can then add repositories. Something similar would work for Symphony: tie your Symphony account to a Github account, and you can then pull repositories across.

Doesn’t solve the versioning problem though. Or extension developers who don’t use Github. Are there any?

I have a github account, but I’m on Windows machine and I have not even installed git on my machine. It didn’t seem very easy to install.

Doesn’t solve the versioning problem though. Or extension developers who don’t use Github. Are there any?

I was… Until last week :)

I have a github account, but I’m on Windows machine and I have not even installed git on my machine. It didn’t seem very easy to install.

Fair point. Using Git wouldn’t be a requirement for all users, only those who want to submit an extension to the site. If you want to write and release an extension, we’d strongly encourage you to use git, regardless of whether the website requires it or not.

I have a github account, but I’m on Windows machine and I have not even installed git on my machine. It didn’t seem very easy to install.

I tried to explain how I did it (back in the days when I was still using Windows) in another thread.

Some thoughts:

• I like how Drupal approaches the problem. Instead of showing a compatibility table with a row for each Symphony release, it would be sufficient to add a new row every time a new version of $extension breaks compatibility with older Symphony versions.

• Forcing developers to use GitHub is a strict requirement, but it’s also true that most of the extensions in the gallery don’t even provide a ZIP package as you can get the tarball from GitHub.

I remember that the old site integrated GitHub for extensions and provided automatic ZIP downloads. GitHub is the defacto standard so I wouldn’t have any problems with a tighter integration.

Was there a reason to drop GitHub integration?

I just think we didn’t want to impose it as a requirement. Github wasn’t quite as ubiquitous back then. We’re reconsidering though…

eKoeS: That “Version - Compatible up to” table doesn’t fix our problem because it doesn’t show past versions this extension is NOT compatible with.

@phoque: Just replace “Compatible up to” with “Compatible with” and here is the fix.

Example (SubsectionManager):

Note:

[me] Instead of showing a compatibility table with a row for each Symphony release, it would be sufficient to add a new row every time a new version of $extension breaks compatibility with older Symphony versions.

I was referring to the public overview — the edit mode probably still requires a list containing all the releases.

Maybe an extension that installs extensions :) ? Like in Joomla!, but it would search this site for compatible extensions?

Edit: That extension would check the compatibility and would not install incompatible extensions…

@miika, yeah that could be possible further down the line once the infrastructure is in place. Even without the extension, Symphony should be consuming this information and preventing incompatible extensions from being installed. That’s why I think it needs to be primarily embedded with the extension itself, and not stored on the Symphony site.

Simone your table is the same as mine, if I understand it correctly. Except I show a range of versions, which I think is less ambiguous.

So where might this information be held?

• extension driver about() array
• a parseable format from the README (yuk?)
• a new format, perhaps a standard XML driver/config/definition file that all extensions must contain?