Symphony.

As I’ve mentioned here it’s often difficult for me to keep track of Extension updates.

Many Extension developers mention updates and/or changes in the discussion thread first announcing the Extension. Others update the Extension Description on the Download page. Again others (seem to) mention little and updates need to be discovered through commit logs on e.g. GitHub.

I think it would be beneficial to have some Best Practices regarding this issue. I would propose to use the Extension Download page and specifically its Description field to describe a Change Log list.

Obviously we’d need some way to be informed of updates. The Discussions seem most appropriate, but I’m not sure: updates are easily missed… Maybe a RSS feed of both http://getsymphony.com/download/extensions/ and individual extensions?

Would love to hear the thoughts of some experienced Symphony users on this (I’m just new here ;-) )

I think the most reasonable way to notify users of extension updates is to inform authors through the Symphony backend itself. Take this idea as a feature request for a future version of Symphony (perhaps Symphony 3?), as I understand it’s not something that can be done that easily.

At the present time, I suggest to work on a RSS feed for the Extensions page, as David suggested.

I’m not fond of using the extensions page (at least if the extension management stays at it currently is) because it leads members to use the built-in issue tracker (which cannot be disabled and which currently offers no notifications). I know that updates are in the works but for me GitHub is the way to go at the moment: You can watch the repositories you are interested in so you get notified about updates. The forum offers everything else you need.

That said, I would love to see this site improved with a better extension management. I just wouldn’t recommend it in its current state.

Nils, good points. This implicates (is it advocated) that Extension Developers use GitHub?

If this is the case it would be great to have some more official documentation around the Git workflow. I know many people struggle with this, evident from the many Discussions around working with Git.

Again: It’s great that there’s much discussion in the Forums on this already, but Symphony seems to struggle a bit with an issue of ‘fragmentation’ (Documentation, Extensions, etc.).

Personally I am fine with GitHub as an ‘offsite’ ‘Hub’ for Symphony Extensions but would welcome some help from the Symphony Documentation WG on how to actually use/update Symphony Extensions (If Git is, in fact, the de-facto standard).

PS: Hopefully I’m not coming across as too critical. I’m very impressed with Symphony and the Community as a whole but, being a newcomer, struggle with the fragmented information.

I think GitHub is the de facto standard: you’ll find the core and nearly all extensions there. As long as you’re are not a developer yourself Git and GitHub are two different things: while you need to use the Terminal to get Git working, GitHub is more a social code network where you can follow programmers or repositories. It’s possible to download packages without even touching Git and it offers RSS feeds for your watched repositories.

I’m not sure what’s the “right” way. As a developer you have to do a lot at the moment when updating an extension: you have to change the version number in the extension.driver.php, update the readme.markdown, push everything to GitHub, go to the Symphony website, update the version number, the release date and the compatibility information, move to the forum and add your change log. If a new Symphony version is released, you should not forget to update the compatibility. Then you have to follow the forum, the Symphony issue tracker, the comments on GitHub and the GitHub issue tracker (which at least offers notifications) …

As a developer you have to do a lot at the moment when updating an extension

Too right! As someone without something stupid like 40 extensions I find is almost impossible to correctly document versions, changelogs and READMEs everywhere.

I know the guys created the Extensions section on this site to be the definitive home of extensions. Using Github isn’t a requirement, but it’s what almost everyone does. If an extension is released as a ZIP file without a Github repo, someone will almost always ask for it to go onto Github. If nothing else, it gives the files permanent home (whereas ZIP files have a tendency to go missing).

If this is the case it would be great to have some more official documentation around the Git workflow

Good plan. I use Gitbox on OSX now, which means I rarely touch the terminal except for very very basic commands (cloning and tagging only). It’s very easy.

I’d personally like to see tighter integration with Github. It’s not a passing fad, it’s pretty much here to stay. By coupling the two and using the Github API one could extract things from the repo:

• list of tagged versions and the commits for each (as a partial changelog)
• a README file that can be presented

If the Symphony member profile allowed us to enter our Github username then we could also potentially show a list of collaborators too.

Obviously this requires developers to follow certain conventions for it to work:

• developers correctly tag releases with version numbers
• developers maintain a README file

The README file formatting convention has changed over the years. It began as plain text (example) and with the move to Github, now people write them using Markdown (example). This is fantastic, and most people follow some sort of convention.

But I think we could try and standardise a bit more. Commit histories don’t make for perfect changelogs — they document the code fixes themselves but do not provide an overview of what has changed in the version. Some people maintain a changelog in the README, others in the Description field on this site, others in the extension forum thread. I prefer to keep the on-site Description very light — I think of it as a description that could be used if the guys want to build a list of extensions: name, strapline and description. To me it is not the place for changelog, installation or acknowledgments. It should describe the extension’s purpose, and not be a piece that evolves much over time.

If a new Symphony version is released, you should not forget to update the compatibility

Nils I recall you wanting to establish a convention of documenting Symphony compatibility in extension driver files. Now, if the extension.driver.php can be found in the Github repo, why can’t it be parsed and the compatibility use on the Symphony site?

I firmly believe that convention trumps configuration. If we’re already updating things in one place (i.e. meta data in files on Github) then we shouldn’t need to repeat it elsewhere.

As for the issue tracker and notifications, I believe that updates are being stored up in this site’s repo to be rolled relatively soon…

At the present time, I suggest to work on a RSS feed for the Extensions page, as David suggested.

There is an RSS feed on the feeds page. But I’ve commented before that having nine separate RSS feeds for this site is insanity and should be consolidated into one master feed.

I’ll just add to this the oft’ quoted motto (heavily used by the microformats and HTML5 community)

Pave the cowpaths.

As a community we have established conventions ourselves over time — we’ve found what works and what doesn’t — and the conventions are now at a point where they can begin to be formalised.

There is an RSS feed on the feeds page.

Whoops! :)

Nils I recall you wanting to establish a convention of documenting Symphony compatibility in extension driver files.

Yes, I remember that the team said that they will implement something similar in Symphony 3, but apparently they only added the field type until now.

If we’re already updating things in one place (i.e. meta data in files on Github) then we shouldn’t need to repeat it elsewhere.

That would be great. I always forget to update the compatibility chart and I never think about the extension’s description on this site.

By the way, I think the old Symphony 2 beta website automatically pulled extension information from GitHub.

Well it’s definitely tehnically possible. Using the PHP wrapper for the Github API I’ve got a quick demo working that pulls in the relevant information for a repository. I do a little inspection on the list of tags to find the latest version (so it only works for repos with tags!), I grab the raw README markdown, and I also attempt to parse the extension.driver.php (with regex) into a PHP array.

http://nick-dunn.co.uk/assets/files/github-api/?user=USERNAME&repo=REPO

For example:

• http://nick-dunn.co.uk/assets/files/github-api/?user=nickdunn&repo=publishfiltering
• http://nick-dunn.co.uk/assets/files/github-api/?user=czheng&repo=tracker
• http://nick-dunn.co.uk/assets/files/github-api/?user=nilshoerrmann&repo=subsectionmanager

That looks nice, Nick. Maybe it would be a good idea to offer — beside the current implementation — a GitHub integration based on this in the developer profiles? I guess it would help a lot.

By the way, in the Subsection Manager’s about array you can find compatibility information although it’s quite basic and not standardized yet. It would be great to have some kind of convention that allows you to define things like “all version lower than 2.1” or “version 2.1 and all its maintenance releases”.