Symphony Extensions Network

The central place to discuss, organize and optimize the Symphony CMS extensions ecosystem.

Note: Besides serving as an issue tracker for symphonyextensions.com and all things related to the extensions ecosystem this repository aims to provide a comprehensive set of best practices, guidelines and resources regarding extension development and maintenance. We encourage every extension developer to not only keep an eye on this repository (watch/star), but to join the discussion and help us build a platform that in the long run finally might define who, what and wherefore the "symphonists" are :)

Chapters

1. 1. Extension Ecosystem
2. 2. Extension Development
3. 3. Extension Publishing
4. 4. Extension Migration
5. 5. Extension Adoption
6. 6. Extension Transfer
7. 7. Extension Consolidation
8. 8. Extension Deprecation
9. 9. Extension Request

3. Extension Publishing

If you built an extension that might also be useful for other Symphony developers you should think about publishing it. Here's a list of best practices you should follow if you want to share your work with the community:

A) Branches, Releases & Version Numbers

1. Use branches to develop and maintain your extension on github. Your basic setup should contain a master-branch (representing the latest stable, tested and documented release) and an integration-branch (that is used for ongoing development and incoming pull requests and should cointain stable code too). Experimental and instable stuff should happen in separate feature-branches.
2. Use releases to publish versions of your extension on github.
3. Use semantic versioning for your extension's version numbers.
4. Use tags to tag your releases with the appropriate version number. Don't follow github's recommendation of adding a prefixed v, just use the plain version numbers as tag (e.g. 1.0.0 instead of v1.0.0)
5. Add a short changelog to each release listing all relevant changes since the previous release.

B) Metadata, Documentation & Licenses

1. Get familiar with the official Symphony Extension Metadata Schema and add a valid and comprehensive extension.meta.xml to your repo.
2. Add a descriptive markdown-formatted readme to your repo explaining what your extension does and how to use it.
3. Keep your readme focussed. You don't have to include everything in here – github wikis are a great way of providing additional documentation, tutorials or examples. ¹
4. If you set up a wiki you should mention it in the readme. A list of links to all wiki pages ain't a bad idea either.
5. Make use of github topics to tag your repo: symphony-cms and symphony-cms-extension are the official recommended tags for each extension-repository. Depending on the scope of your extension you might also want to add more specific topics (following the symphony-cms-xyz-syntax, e.g. symphony-cms-multilingual).
6. Add a valid licence to your repo – MIT is a good choice that's used by Symphony itself too.

C) Publishing Platforms

1. Publish your extension on github
2. Publish your extension on symphonyextensions.com
3. You might also want to spread the word in the official chat or forums to get some feedback about your extension.
4. The official Symphony website also houses a collection of extensions but we don't recommend publishing new extensions there at the moment.

^{1) This holds especially true if you plan to include tables in your readme – they're not supported on symphonyextensions.com and are better of in a wiki.}

5. Extension Adoption

If you own extensions that you no longer want to support, update or care about we'd encourage you to take the following steps to help us find a new home for them:

1. Submit a new issue (one per extension).
2. Give it a descriptive title: "Extension Adoption: Extension Name".
3. Add a link to the extension repository.
4. Optionally add a short statement about the current state of the extension.
5. If possible give Nicolas (@nitriques) admin access to the repo so he can manage the transfer for you. ¹

Depending on the state, popularity and usefulness of the extension we will then either …

• … try to find a developer who is willing to take over ownership and further maintenance/development.
• … transfer the repo to the symphonists organization and provide best possible support there.
• … mark the extension as deprecated and transfer it to the "symphonists archives".

If you don't give Nicolas admin access to the repo we'll need you to take action after a solution is agreed upon. Thus it would be great if you could keep an eye on the discussion and be available to manage the repo transfer yourself.

^{1) If the repository is owned by a user account you might need to set up a temporary organization to give other users permission to transfer the repository. Please refer to the github help for details about transferring a repository and repository permission levels.}