Modules versioning

[g4b0]

Hi all,
Some days ago I was upgrading as SS installation from 3.1.0-rc1 to the newest 3.1.5 through composer. All modules installed in this site was "dev-master", so updating the system I updated them too. The problem arised with the newest version gridfield-bulk-editing-tools, that broke some API I was using. No problem, colymba is a good developer and he use the git tagging feature to mark each version, so I rolled back to version 1.6.0 and everithing works fine now.
I think that in a production environment it's better to upgrade just in case of security fix, but right now a lot of module out there have just a dev-master version (including silverstripe-widget module), so upgrading through composer will always keep the code to the cutting edge, including API changes, and a rollback it's not always an easy task.
What do you think to make modules tagging mandatory in some way, starting from silverstripe managed modules?

My 2 cent
g4b0

[James Cocker]

Agreed. It would be good to have some solid, yet straightforward documentation written about this too, to explain the best practices.

In the past I have had to tell composer to get a specific commit: https://coderwall.com/p/ub4ejg But this is obviously a last resort.

James

[Cameron Spiers]

In my experience the PHP community promotes semantic versioning:

Given a version number MAJOR.MINOR.PATCH, increment the:

1. MAJOR version when you make incompatible API changes,
2. MINOR version when you add functionality in a backwards-compatible manner, and
3. PATCH version when you make backwards-compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

This versioning differs from SilverStripe's versioning scheme as in SilverStripe breaking changes can go into minor releases, but that doesn't mean your modules have to follow the same scheme.

 

https://igor.io/2013/01/07/composer-versioning.html

https://igor.io/2013/02/07/composer-stability-flags.html

http://semver.org/

--

Cam Spiers Senior Developer

Mb. 021 431 441   Ph. 04 831 5130   heyday.co.nz

--
You received this message because you are subscribed to the Google Groups "SilverStripe Core Development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to silverstripe-d...@googlegroups.com.
To post to this group, send email to silverst...@googlegroups.com.
Visit this group at http://groups.google.com/group/silverstripe-dev.
For more options, visit https://groups.google.com/d/optout.

[g4b0]

Is it possible to upgrade just a module through composer, or I have to upgrade the entire system every time?

[stojg]

I'm very much for tagging code releases as much as possible, but I think it's going to be hard to enforce it.

Would it help to create a full a full section in the documentation about best practices for module maintainers? @Cam Findley was this brought up during the recent Wellington hackfest and the documentation redux?

[Marcus Nyeholt]

Several eons ago I started to put together a script that would automatically inspect my repositories once a month* and check for any changes - if found, it would create a new point release tag for  the module. If I committed something more important, I would be responsible for creating a minor release tag. The motivation for this is largely around what's described - people know that if there's going to be an update, it'll be available at the end of the month. 

Never got around to finishing it though... :)

* or some other pre-determined length of time

On Tue, Jul 8, 2014 at 7:40 PM, stojg <stojg.l...@gmail.com> wrote:

I'm very much for tagging code releases as much as possible, but I think it's going to be hard to enforce it.

Would it help to create a full a full section in the documentation about best practices for module maintainers? @Cam Findley was this brought up during the recent Wellington hackfest and the documentation redux?

--

[Nicolaas Thiemen Francken - Sunny Side Up]

some small ideas below:

(1) automated tagging

Marcus, that sounds like a great idea. Where would your code run? 

What if, when a commit is made to a repository which has not been committed to for a long time, a tag (or hash record - see below) would be created automatically before the commit takes place.  

Maybe addons.silverstripe.org could make a note of the git versions like that (not creating a tag but recording the hash that relates to a point - just before a new commit series). 

(2) different versioning system

There are lots of modules out there with the following sort of tags:

"master"

0.1

0.2

0.3

What if the 0.2 would be something like 3.1.5 - meaning - this tag was created after it was tested against framework 3.1.5 (and 0.1 could be 2.10.1).  I am saying that because it takes a bit of time for  a developer to choose the "matching" module tag for their project. 

--

Nicolaas Thiemen Francken
  www.sunnysideup.co.nz

  phone: +64221697577

--

Nicolaas Thiemen Francken
  www.sunnysideup.co.nz

  phone: +64221697577

[Jeremy Thomerson]

On Tue, Jul 8, 2014 at 6:51 PM, Nicolaas Thiemen Francken - Sunny Side Up <nfra...@gmail.com> wrote:

What if the 0.2 would be something like 3.1.5 - meaning - this tag was created after it was tested against framework 3.1.5 (and 0.1 could be 2.10.1).  I am saying that because it takes a bit of time for  a developer to choose the "matching" module tag for their project. 

The problem is that many modules have a many-to-many relationship to the versions they run on. Naming them this way indicates a one-to-one. Also, you'd need to be able to have multiple versions of a plugin for a given SS version. Say SS is at 3.1.7 for a while, and in that time I release three versions of my plugin. Now I need 3.1.7.1, 3.1.7.2, 3.1.7.3. But 3.1.7.3 also runs agains 3.0+.

This kind of problem is generally only solved with deliberate thought on the part of the plugin developer and good documentation (or documenting it in a dependency management system), or else like Wordpress does where users can vote on the compatibility of a plugin with a certain WP version (essentially crowd-sourcing the data gathering/testing process)

[Ingo Schommer]

Suggested release management for modules is documented on http://doc.silverstripe.org/framework/en/topics/module-development#versioning, although its mainly focused on making different release branches for the sake of core compatibility. Could somebody update this to point to semver.org, explain why its useful, and add a pointer about tagging to http://addons.silverstripe.org/submit? Anywhere else we should mention this? But yeah, documentation is one thing, its really hard to enforce. We could make it more attractive to module maintainers by adding a warning on addons.ss.org if a module a) doesn't have any releases, or b) had more than a month of commits not contained in a release.

[Cam Findlay]

This is something that I have been playing with on the side (among the bazillion other things) - but I have recently implemented an experiment on the forum module to flesh out a simplified process for versioning modules which ends up working like a cut down git-flow (which I find a bit too full-on for a module https://www.atlassian.com/git/workflows#!workflow-gitflow). The idea is to make it an easy suggested workflow for modules to get started, a "good practice" however others may have their own processes which I think is ok too.

It works like this...

master - accepts any breaking changes or more radical enhancements, ideally like the current versioning that Ingo pointed out above this should work with the current master of SilverStripe core (but I understand there will be edge cases here).

numbered development branches (0.1, 0.2, 1.0 etc) - at some point you'll need to start with some sort of numbered branch, suggest if it is a new module you start with a 0.1. This is a branch NOT a tag. Non-breaking changes, enhancements, bug fixes should have pull requests against these. 

Release tags - When a reasonable amount on fixes have taken place in the numbered development branch you may tag a patch release 0.1.1, 0.1.2. 

New branches - When a reasonable or planned amount of new minor breaking features have been introduced into master you would make a new minor point development branch 0.2 and tag a release: 0.2.0.

If a major refactor/rewrite has occurred, you'd tag this as a major release 1.0.

Porting - Over time fixes and enhancements in numbered dev branches get ported up into master.

Rinse and repeat.

Some other points

To deal with which versions of SilverStripe the module works with 1) ensure your readme file exists and states the version, 2) Ensure you have a composer file that deals with dependancies 3) make a decision on how long you really want to support the older version of your module.

Ideally in github you set the HEAD to the current stable release branch ie 0.2 if we are following my above example.

Noted that you may also end up having some other working feature branches too while you are working on various things (like massive rewrites) but I think this versioning is simple and robust enough to follow for people just getting into module creation and encourages the practice of releases.

I would also suggest making use of the github milestones etc to help track and communicate to others what you are working on and where the module is going.

This might not be perfect, as I say I'm still experimenting with this approach over on the forum module but with a bit of fine tuning and help from you guys I think we could look at combining this with the documentation we already have to start getting some better versioned releases and away from the constant dev-master approach we have at present.

[Loz Calver]

Another added bonus: composer can cache tagged releases. Makes installing SO much faster!

[Cam Findlay]

My thoughts exactly.

[Simon J Welsh]

You can get the same behaviour for branches by providing the --prefer-dist option. Likewise, you can get the VCS version of a tag by using --prefer-source.

> --
> You received this message because you are subscribed to the Google Groups "SilverStripe Core Development" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to silverstripe-d...@googlegroups.com.
> To post to this group, send email to silverst...@googlegroups.com.
> Visit this group at http://groups.google.com/group/silverstripe-dev.
> For more options, visit https://groups.google.com/d/optout.

---
Simon Welsh
Admin of http://simon.geek.nz/

[Martimiz]

In the documentation it says:

As a convention, the master or trunk branch of your module should always work with the master branch of SilverStripe.

Do you still hold on to that? Or can a modules master branch be its own development branch? So if I were to develop some new features based on my latest branch, where would they live If they do not yet support the latest developments in Framework and cms master?

Martine

[Nicolaas Thiemen Francken - Sunny Side Up]

Hi Everyone

Not sure of if the below is helpful:

For me, when I am developing a little module, I usually do this as part of a client project. This means that the module I am working on is being developed against something like a 3.1 branch or a 3.1.4 tag. In other words, the master of my module (which may not have any versions yet) works for the latest SS release and while it may work with master - it is another job to do - so why not let the "master" of a module be linked to a particular version of SS? 

I guess what I am saying is: the easier it is, the more likely people will follow it. I have personally never developed a website that runs on SS master so it is unlikely that my module will work with SS master.

Nicolaas

​