Plugins should move quickly and break things

[daftspunk]

Reference: rainlab/user-plugin#73

Story

Charlie has released an amazing affiliate marketing plugin for OctoberCMS. Over 100 websites are using the plugin to manage click tracking and pay commissions.

Later, Charlie realises that perhaps he could have coded the plugin a little better. Unfortunately it means he needs to introduce features that may break websites already using the plugin.

Charlie wants to create Version 2 of the plugin and without hurting the developers who rely on the older code in the original version (Version 1).

Proposal 1

Note: This is an older solution and the existing infrastructure partially supports it, including the ability to solve a parallel issue (#784 Core and Plugins should support a Test build) whereby a test package can be used.

Charlie is able to log in to the OctoberCMS website and create a new "build" for his plugin. The current build (Version 1) is called stable by default. All the current users are allocated to the stable build.

Charlie renames stable to version1 [complex: data integrity]. He creates another build called version2.

Charlie also creates a version1 and version2 branch in his git repo. The git branches are then linked to the October builds.

Charlie can continue to maintain both versions easily. New users will receive the version2 build by default, exisiting users will remain on version1 unless they voluntarily decide to opt-in for version2.

Users can opt-in via some form of GUI:

• Using the Project management screen on OctoberCMS.
• For unbound plugins, via the Bakend area [complex: UI].

The benefits of this proposal are that Charlie can continue to maintain version1 in the future. The downsides are the complexity of this solution is significant.

Proposal 2

Plugins currently use a version.yaml file to define their history, these follow semantic versioning with MAJOR, MINOR and PATCH numbers, where v1.2.3 is major version 1, minor version 2 and patch version 3. This proposal places greater importance on the MAJOR segment of the version number.

Charlie has so far kept his plugin at v1.0.78. Now that he has decided to release a new version, he bumps the plugin to v2.0.0. This is a significant event for the plugin management process.

When the build server sees an increase in a MAJOR version, it will retain a locked snapshot of the previous version.

When October's update process sees a plugin is attempting to increase a MAJOR version (eg: v1.x to v2.x, or v1.x to v4.x) it will prompt the user.

The plugin "Charlie.Affiliates" wants to update from v1.0.78 to v2.0.0, 
this may result in breaking changes that require attention.
Do you want to proceed with this update?

                         [ YES | NO ]

(This cannot be undone. If you are unsure, click NO.)

If the user selects "NO", the plugin is added to a Do not update list and future updates will be ignored. If the user selects "YES" then the plugin is updated as normal.

When a project, plugin or theme depends on Version 1 of the plugin, the server will deliver the locked snapshot version.

The benefits of this proposal are the greater simplicity. The downsides are that once a plugin enters a new version, the old [locked snapshot] version can no longer be maintained.

Proposal 3

If an update.yaml comment begins with three !!! then it will be considered "Important" and will require the user to confirm before updating, the plugin will present 3 choices:

• Confirm update
• Skip this plugin (once only)
• Skip this plugin (always)

Example:

1.1.0: !!! Profile fields have been removed. Locations have been removed, install RainLab.Location to bring them back.

[daftspunk]

Prefer Proposal 2

[shina]

Proposal 2 +

I'd add only one thing on the warning message, some way to the user read a document explaining the impacts of the update and how it can be done.

Maybe this document could be a markdown commited together with the plugin files and in version.yml file this document is linked together with the version descriptions.

On Fri, Nov 21, 2014 at 4:32 AM, Samuel Georges notifications@github.com
wrote:

Story

Charlie has released an amazing affiliate marketing plugin for OctoberCMS. Over 100 websites are using the plugin to manage click tracking and pay commissions.
Later, Charlie realises that perhaps he could have coded the plugin a little better. Unfortunately it means he needs to introduce features that may break websites already using the plugin.
Charlie wants to create Version 2 of the plugin and without hurting the developers who rely on the older code in the original version (Version 1).

Proposal 1

Note: This is an older solution and the existing infrastructure partially supports it, including the ability to solve a parallel issue (#784 Core and Plugins should support a Test build) whereby a test package can be used.
Charlie is able to log in to the OctoberCMS website and create a new "build" for his plugin. The current build (Version 1) is called stable by default. All the current users are allocated to the stable build.
Charlie renames stable to version1 [complex: data integrity]. He creates another build called version2.
Charlie also creates a version1 and version2 branch in his git repo. The git branches are then linked to the October builds.
Charlie can continue to maintain both versions easily. New users will receive the version2 build by default, exisiting users will remain on version1 unless they voluntarily decide to opt-in for version2.
Users can opt-in via some form of GUI:

• Using the Project management screen on OctoberCMS.
• For unbound plugins, via the Bakend area [complex: UI].
  The benefits of this proposal are that Charlie can continue to maintain version1 in the future. The downsides are the complexity of this solution is significant.

  Proposal 2

  Plugins currently use a version.yaml file to define their history, these follow semantic versioning with MAJOR, MINOR and PATCH numbers, where v1.2.3 is major version 1, minor version 2 and patch version 3. This proposal places greater importance on the MAJOR segment of the version number.
  Charlie has so far kept his plugin at v1.0.78. Now that he has decided to release a new version, he bumps the plugin to v2.0.0. This is a significant event for the plugin management process.
  When the build server sees an increase in a MAJOR version, it will retain a locked snapshot of the previous version.
  When October's update process sees a plugin is attempting to increase a MAJOR version (eg: v1.x to v2.x, or v1.x to v4.x) it will prompt the user.

The plugin "Charlie.Affiliates" wants to update from v1.0.78 to v2.0.0, 
this may result in breaking changes that require attention.
Do you want to proceed with this update?
                         [ YES | NO ]
(This cannot be undone. If you are unsure, click NO.)

If the user selects "NO", the plugin is added to a Do not update list and future updates will be ignored. If the user selects "YES" then the plugin is updated as normal.
When a project, plugin or theme depends on Version 1 of the plugin, the server will deliver the locked snapshot version.

The benefits of this proposal are the greater simplicity. The downsides are that once a plugin enters a new version, the old [locked snapshot] version can no longer be maintained.

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

[connecteev]

Prefer proposal 2. The way I see it, most developers using October will not author their own plugins, and do not closely follow the octoberCMS dev roadmap (let alone every plugin's development), so they should be explicitly notified.

2 ideas:

1. Once added to the "Do not update list", the user should be able to easily access this list and update any plugin if he so chooses to -- this should be easily visible in the backend UI.
2. With proposal 2, maybe the old [locked snapshot] version can still be maintained if the plugin developer continues to submit plugin changes with an old major revision number, like 1.x.x

[dshoreman]

One more vote for proposal 2, also with the second point @connecteev mentioned.

It's possible the plugin developer may release a critical security update to v1 after the release of v2. Perhaps there could be a way of blacklisting major updates, while continuing to update if update_major_version == installed_major_version. That way there are no unexpected breaking changes, but people aren't stuck with a potential security risk either.

This starts to leak over into proposal 1 though. I guess the ideal scenario would be one similar to how composer itself works, whereby you can specify a branch or tag to follow, for instance "dev-master" or "1.x.x". The downside to this is it assumes plugin developers tag their releases in Git,

[NemoD503]

+1 to proposal 2

[abass]

+1 for proposal 2, but I do agree with @connecteev definitely if you go this route. I'm hesitant to even give my clients control over software updates though as I worry if they update when they shouldn't, it could break things and then I have to fix them.

This is why @dshoreman's point seems very valid though too. If we end up keeping the client off v2.0 and unbeknownst to me, a huge security flaw happens on v1.0, the package controller should be able to still update v1.0 to fix it for those who chose not to update. I don't think it would hurt to have it work similarly to composer and bring in some more structure with tagging your releases in Git.

[manogi]

+1 for proposal 2 and +1 for the point @connecteev made.

[dubcanada]

+1 proposal 2

I would also not mind seeing some sort of a changelog when updating a plugin. I can usually get a decent idea of if I can update fine with such a thing.

[dshoreman]

@dubcanada The Changelog plugin would be a great place to add that sort of thing. I'd be happy to merge a PR if you want to add functionality that scans plugins.

Pull requests can be made to the develop branch; I can't remember the code off-hand but PluginManager::instance()->getPlugins() should give you a good starting point

[Eein]

+1 proposal 2, but thats assuming people are being good and using semantic versioning :(

[romaldyminaya]

+1 proposal 2, I loved it :)