Semantic Versioning

[Hamish Friedlander]

Hi Everyone,

Something that came up again in the discussion around namespacing at https://github.com/silverstripe/silverstripe-framework/issues/3548 is that SilverStripe doesn't currently follow the principles of semantic versioning (http://semver.org). 

While there are both historical and technical reasons for that, we’re not really tied to the current versioning semantics by anything except inertia, so it’s worth examining if we want to adopt semantic versioning as a new standard.

Right now, our versioning semantics are something like this:

 - Point release: bug fixes and minor changes that don’t substantially affect user experience

 - Minor releases: only include changes that can be resolved easily by developers, e.g. through the execution of a tool or by following a few clearly-defined steps

 - Major releases: significant refactoring might be required

Semantic versioning is described fully at http://semver.org, but is roughly:

 - Point release: bug fixes, no new features

 - Minor releases: new features/APIs, but no compatibility-breaking changes

 - Major releases: significant redacting might be required

If we switch to adopting semantic versioning, then our version scheme won’t distinguish between “some small changes are required” and “major changes are required”, which our historic versioning scheme as done.

There will be some other effects of moving to semantic versioning:

 - Once a minor release is out, point releases must only contain bugfixes. All new features will need to wait for the next minor release.

 - There is likely to be more frequent minor releases

 - There is likely to be more frequent major releases

 - More frequent releases means existing releases will be end-of-lifed faster

 - It will be clearer what versions of SilverStripe a module will work with

Specifically, it’s likely there wouldn’t be a 3.2 release, and there would be a 4.0 instead. 3.1 would move into security-fixes-only support mode about 6 months after that release.

In order to mitigate the effect of more frequent backward-compatibility-breaking changes, we would introduce a new open source commit policy around providing more assistance for upgrading between major versions. It might be something like this:

“For any API change, one of the following must be provided, in order of preference:

A script that transforms project/module code to suit the new API

A script that identify potential areas that need to be fixed

A section in the upgrade guide that explains the changes that need to be made”

So, what do people think? Should we shift to using semantic versioning?

Hamish Friedlander

[Loz Calver]

I’m in favour of switching to semantic versioning, and am definitely in favour of more frequent releases - especially point releases. It’s often a matter of months between a bug fix being merged and the next release. While I’m not saying we should target weekly releases or anything, I think the timescale of point releases is something we could improve on with semantic versioning (no new features in point releases that need time to mature and be thoroughly tested).

More frequent releases would, presumably, mean an increased workload on the core team. I understand that the release process for the person who actually has to tag the release, update the website etc isn’t an easy one: I vaguely recall seeing a surprisingly long document detailing the process.

If we switch to adopting semantic versioning, then our version scheme won’t distinguish between “some small changes are required” and “major changes are required”, which our historic versioning scheme as done.

I guess the theory here is that with more frequent major version releases, you’re less like to end up in a situation where one release contains lots of major changes. If/how this will work out in practice for SilverStripe I’m not really sure, but I think the new policy you suggested about upgrade tools and/or docs would alleviate the upgrade hassle should this happen.

Specifically, it’s likely there wouldn’t be a 3.2 release, and there would be a 4.0 instead. 3.1 would move into security-fixes-only support mode about 6 months after that release.

Entirely out of curiosity: why would we skip 3.2? Is it because there are already a number of breaking changes, so a major version bump would be more appropriate? Or just to switch to semantic versioning now rather than delay until 3.2 is out?

Loz 

[Hamish Friedlander]

Specifically, it’s likely there wouldn’t be a 3.2 release, and there would be a 4.0 instead. 3.1 would move into security-fixes-only support mode about 6 months after that release.

Entirely out of curiosity: why would we skip 3.2? Is it because there are already a number of breaking changes, so a major version bump would be more appropriate? Or just to switch to semantic versioning now rather than delay until 3.2 is out?

I'm assuming that the ORM rewrite is a big enough change it needs a major rev in semver, although I'd be interested in tractorcow's feelings there. If it isn't, then we could probably do a 3.2 - in which case replace 3.2 with 3.3 (since there are several features that I'm hoping we'll get to sooner rather than later which will break backwards compatibility).

Hamish Friedlander

[dam...@silverstripe.com]

To keep things in perspective, if we were following the semantic versioning standard since 3.1, we would probably be up to 3.12.0 about now. :)

My feeling about this change in practice is a "yes definitely" but with a mind to be respectful of the expectations we've already raised in the SS community. I don't feel it's reasonable to break these expectations by releasing what's currently in master as 4.0, because we've been calling this "the 3.2 branch" up until now. (composer require silverstripe/framework 3.2.*-dev installs master currently).

If we were following semver until now then we should put this into 4.0, but the fact is we haven't been doing this, we are only planning on doing this in future.

I propose that we accept that we have over-committed to the level of changes we have allowed in 3.2, but that we continue to deliver this release based on the current code base. The ORM is not a fully backwards compatible change, as there are API changes and deprecation notices in some cases, but in many cases there is no API changes necessary (several tested modules have required no or only very minor changes).

I think it would be better to branch our current master into 3.2, and from then on use semantic versioning, aliasing the new master as 4.0. This doesn't require us to release 3.2 immediately, but at least will better define what will be in that release (and more importantly, which won't be).

That way users who were relying on the new features included in the ORM rewrite will not have to choose between either, A: Going back to 3.1 or B: Being forced to migrate to a very bleeding edge and volatile API.

We are looking at doing a large amount of refactoring in (what I'll assume is 4.0 for now). Making a backend-independent filesystem, namespacing all classes, replacing and/or refactoring all versioning, and so on.

The next question is how to deal with multiple future release branches, since the assumption is that we might want to introduce new features once 3.2 is released, so I assume we would branch 3.2 into 3.3 after 3.2.0 is out. Unless we wish to follow develop a new git workflow as well. :)

Kind regards,

Damian

[Loz Calver]

I was also trying to wrap my head around the implications that this switch would have on git! I agree with all your suggestions about releasing 3.2 “as-is”, a couple of points though:

As soon as 3.2.0 is released, we’d create a 3.3 branch - from the targets I’ve seen on uservoice, it’s plausible that 3.3 might come before 4.0, so this will certainly be needed. How long do we keep this up for, though? As soon as a 3.x.0 is released, do we always create a new branch 3.(x+1) just in case new features are to be added? Or would a user have to approach a core member and say “I want to add a new feature, can you create a new minor branch that I can do a pull request against”? I guess the same question applies to the 4.x releases too.

On which branch would we switch to semantic versioning? Would 3.2.0 mark the start of it, so only bugfixes and no new features can go in 3.2.1? Or do we keep the 3.x versions running as-per our current versioning system and only start using semantic versioning the 4.0+ releases?

Loz

[Uncle Cheese]

I'm really glad this has come up! It's been a pain point for me ever since I learned what semver was. :-)

I'm totally supportive, and I think it's fair to say that most developers are, and that it's less a question of if, but rather, when, it should happen.

Given the turbulence caused by the 3.1 "minor" release, my position is that I'd rather not history repeat itself. That release didn't sit well with developers and users alike, especially those users who had to pay their developers heaps of cash for a "minor" upgrade.

My vote is to stop the train, in spite of its inertia, and jump into a plan for 4.0 as soon as we can. It may seem weird to have a major release without any significant UX changes, but there's plenty of precedent for that. iOS didn't get a makeover until its 7th major release. So maybe it's just a question of managing expectations. Following the semver pattern is the best way to do that, I think.

[Will Rossiter]

Given the turbulence caused by the 3.1 "minor" release, my position is that I'd rather not history repeat itself. That release didn't sit well with developers and users alike, especially those users who had to pay their developers heaps of cash for a "minor" upgrade.

Semvar isn’t going to solve that. Upgrade pain is still going to be upgrade pain, you simply change the label people rant about whether it be 3.2 or 4.0. We want to encourage upgrades, not people staying on older code.

But semvar + 1 for me as it at least some form of standard framework to operate in rather than making it up as we go. Might as well start now with a 4.0. Enough to justify a major release IMHO (just see the changelogs.). If not, few of those things in ‘Planned’ could land, then a release set and we go from there.

I’m in favour of switching to semantic versioning, and am definitely in favour of more frequent releases - especially point releases. It’s often a matter of months between a bug fix being merged and the next release.

I agree. Currently 3.2 (master) has a mix of general “this bug fix is too big for 3.1, but it’s a good fix”, and “the world will end API changes” that have dropped in over the last 12-14 months. 

This would give us the framework to push something like a ‘3.2' containing any non security, non api changes to 3.1 (like the old ‘post-2.4 branch) while having the 4.0 for major suff. (We wouldn’t do this retroactively but for 4.x it’ll come into play).

More frequent releases would, presumably, mean an increased workload on the core team. I understand that the release process for the person who actually has to tag the release, update the website etc isn’t an easy one: I vaguely recall seeing a surprisingly long document detailing the process.

Things like that are the core team’s problem. We could script that shit if warranted. Release cycle should be there to make it easier for community to understand rather than the poor core guys doing the releases :)

A script that transforms project/module code to suit the new API

The infamous upgrade script that has been banded around for the last few years I’ll believe it when I see it :)

[Damian Mooyman]

For me it seems the most important thing semver would provide is a wider range of options that users can now target features against. At the moment users can target 3.1 or master (3.2). We currently have three different shaped pegs but only two holes.

Maybe our branches could (but is realistically unlikely to) look something similar to the below:

- The next major release (master, aka 4.0) - Breaking api changes

- The next minor release (3) - To be included in next release (branched into 3.x on release of new API)

- The next patch release (3.1, 3.2, etc)  - Non-api fixes

Merging up bugfixes from older branches to higher ones is going to become a lot more complicated. As are version releases.

Kind regards,

Damian Mooyman | Senior Platform Developer

SilverStripe

http://silverstripe.com/

Phone: +64 9 281 3498

Skype: tractorcow

--
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.

[Hamish Friedlander]

In terms of git, I'd expect a branch per major & minor release

3, 4, etc (or 3.x, 4.x, etc ) for the major release branch, which the minor releases come off.

3.0, 3.1, 3.2, 4.0 (or 3.1.x, etc) for the minor release branches, which the point releases come off.

master for the upcoming major release

I wouldn't expect we would try and forward merge patches across the major release gap - fixes for 3 would stay in 3. I also wouldn't expect us to have many changes in old branches. I would be very surprised if there was a 3.x release after 4.0 came out. Similarly, once 4.0 is out, most features and bug fixes are going to be targeted for 4.0, even if theoretically they could be applied to older versions.

As far as release frequency - one advantage of changing to SEMVER is that point releases can hopefully be automated. Point releases become sort of an anachronism anyway (since every change on a point release branch should by definition only fix bugs, so any commit should be useable as a release).

I can see both sides of the issue on whether we do 3.2 or move straight to 4. I probably am slightly on the "do a 3.2 first" side. There's been no expectation of the 3 line following SEMVER, so having a single further minor release in that line which follows our existing policy is both reasonable and valuable - it allows people using master to move to a release without worrying about bigger breaking changes. Of course, once 4.0 is out they'll need to upgrade anyway, since most improvements and bug fix effort will move to there, so maybe the effort of the release isn't worth it. Keen to hear from people who _are_ currently basing projects on master to get their view point.

Hamish Friedlander

[Stevie Mayhew]

I think that moving to a semantically versioned release cycle makes sense, and I can see the benefits of relying on a SemVer release cycle greatly outweighing any cons which may come up.

However, this is going to cause a world of hurt for module development as it stands at the moment. Currently there isn't really a great way to work out how to target a large percentage of modules due to their non-standard release patterns. I would advocate making an effort to standardize the modules that are part of the CWP and silverstripe/silverstripe-labs repos into a SemVer release cycle before pushing anything through in the master branches. This would also be a good chance for us all to start tagging our modules and start targeting the correct branches of SilverStripe. Eventually I'd love to remove the `minimum-stability: dev` flag from my composer and just have `whatever-module: *` automatically work out which version should be pulling itself in based off the target of SS which I've defined. Obviously this is up to module authors to be able to make it happen, but having the main repos in SemVer should make it a lot easier to handle.

I think that if we decide to start semantic versioning we should bite the bullet and do this at the earliest possible moment - meaning that IMHO a 3.2 release doesn't make sense as then we would be maintaining a 3.2.x and 4.x.x release which aren't in line with each others versioning. This could become unwieldy, again with focus on modules and module authors being my main concern (always thinking about myself, I know)

By the way, it's great to see these discussions going on :)

[dam...@silverstripe.com]

I think at the moment we are really just talking about framework and CMS. At the moment we don't really have a formalised release process for the majority of our modules, other than a few that are being stewarded by a few dedicated community members.

I think the important thing is to develop the process and get people using it in core. If we have people willing to take on the responsibility then we can extend this process to a _few_ core modules, and not necessarily CWP ones.

[Hamish Friedlander]

While there's been some points around "3.2 or straight to 4" and some technical issues raised that I'd like to keep discussing, generally it seems everyone's in favour, and I haven't seen anyone say moving to SEMVER would be a bad idea. 

So I think we can make the call that we will move to SEMVER (although we've yet to figure out exactly what the transition will look like).

Hamish Friedlander

[Loz Calver]

I wouldn't expect we would try and forward merge patches across the major release gap - fixes for 3 would stay in 3.

This sounds fine to me - it’s more-or-less the same as it is at the moment. I envisage fixes in 4.0.5 being merged up to 4.1.x, but as there aren’t going to be any API changes this shouldn’t often be a problem.

I like the idea of switching to semver immediately and starting with 4.0 now, but with namespacing etc still to come I feel this may be a long, long way in the future. I think we’ve got three options:

1. Release 3.2 soon, don’t worry about semver on anything <4.0

- Make current master 4.0 and either:

    2. Delay the release until namespacing and associated changes are done

    3. Release it sooner and make namespacing and associated changes 5.0

Out of those three options, my personal preference is the second.

[Sam Minnée]

If we're going to follow semver then we'll stop putting new features into 3.1. If we wait until namespacing is done and stablised, then it seems like we're not going get new features out for a long while, which feels a bit sub-optimal.

We could, in theory, create a new minor release by branching 3.2 from the 3.1 branch. However, that would be very confusing for people who currently access master as 3.2.x-dev—they'd have all the master features disappear—so I see that as too confusing to be viable.

So, perhaps it's better to get a new release out with that we've currently got, and stabilise that over the next few months. There are two options for that. I've matched the numbering to be the same as your email.

 1. Release what we have as 3.2 and start work on 4.0, which would likely include namespacing. 

Rationale: We've already set the expectation that what's on master will be released as 3.2, and changing the goalposts isn't fair. 3.1 wasn't a semver release and so there's not much value in pretending the 3.x release line is now. Starting semver with 4.0 is cleaner.

 3. Release what we have as 4.0 and start work on 5.0, which would likely include namespacing.

Rationale: The ORM rewrite, or though it was mainly backwards-compatible, would be too big for a semver minor release if we were starting on it now. If we're going to say "let's follow semver for our releases" then we should make our next release semver complaint, it doesn't matter that 3.1 wasn't a semver minor release.

Although I'm a bit concerned with option option #2 for the reasons described above, I'm struggling to pick between #1 and #3.

[Mark Guinn]

My vote would be #1 here. Release 3.2 soon as is and leave namespaces to 4.0, but don’t try to cram too much else into 4.0 so it can be released sooner.

[Simon J Welsh]

Something that I haven’t seen brought up in this thread but needs to be. Module requirements.

The current recommendations for listing the silverstripe/framework or silverstripe/cms is to use ~3.1. This means most dependencies are written in a way that assumes that framework and cms already follow semantic versioning. This is part of the reason I tried to make sure the 3.2 ORM rewrite is backwards compatible.

As such, without causing basically every module to break again (yay, totally preventable massive BC breaks in the RC stage for 3.1), 3.2 should follow semantic versioning. If I had my way, then all deprecation notices introduced as part of 3.2 wouldn’t trigger until 3.3 either.

This can be achieved by branching from master to a 3.2 dev branch, then fixing the breakages. Won’t need to fix them all, but most modules should be able to run on 3.2 without changes.
---
Simon Welsh
Admin of http://simon.geek.nz/

[Sam Minnée]

Branching 3.2 and fixing any BC-breakages evidenced by modules seems like a good approach to me. That gets my vote.

Damian - what issues are we likely to see with the ORM rewrite? My expectation is that if we have remaining BC issues (e.g. with augmentSQL) we would patch the 3.2 branch to favour compatibility over cleanliness, and leave the current implementation as the basis for 4.0.

[Damian Mooyman]

I think this is going to be semi-achievable; In the 3.2 ORM rewrite there were a few things which were developed in a way which were not completely deprecable (as in, usages wont automatically continue to work but with a deprecation warning).

It's still going to be impossible to remove all of those instances, but there are places where we can revert certain API changes and instead mark those as deprecated in 4.0. see  https://github.com/silverstripe/silverstripe-framework/blob/master/docs/en/changelogs/3.2.0.md for (what should be) the list of all changes necessary.

The most notable change that I think could probably be reverted is the new SQLSelect class. It might be easier to actually rename SQLSelect back to SQLQuery and keep the old class name, meaning that old DataExtension::augmentSQL methods will not need to have their signature changed, and fewer api changes will be necessary. The behaviour will still change slightly, but we won't have immediate breakages of API. This WILL mean that changes already made to some modules (e.g. translatable maybe) will need to be reverted for 3.2.

I think just about anything in SS_Database that has changed has a deprecation notice with fallback, but it deserves another check.

We could also revert the changes to beginSchemaUpdate, but that code shouldn't really be used by modules. That doesn't mean no one is though, but I think the risk is likely low.

Most of the non-breaking api deprecations were set at 3.3, but a lot were still immediately deprecated at 3.2 so I suggest another review to move that deprecation up another minor version. Some breaking changes will need to be immediately deprecated though if the change broke any existing api expectations.

However, just about any method that deals with handling SQL queries at a very low level is going to have issues with the new query parameters, and will still need manual upgrading.

Kind regards,

Damian

[Daniel Hensby]

A bit late to the party here, but here's what I think:

- Moving to semver is a good idea and we should do it

- There needs to be a decision on when to move to semver

- Semver will have other implications that need to be consisdered, it's not as simple as many in the thread are making out

- Decisions need to be made about:

    - release schedule

    - support commitments

    - end-of-life plans

__Moving to semver__

This is a great idea, as composer is being used more and more we really need to move to semver so that we can all make use of the version numbers with some certainty. It'll 

also remove any ambiguity about whether "this change is too big for 3.1".

When to move to semver isn't quite as simple as saying "3.2 should be 4" or "lets get 3.2 out and next is 4" because of the fact that we need to understand the support 

commitments that the current 3.1/3.2 branches should get and what the 4.x support commitments will be. Read on.

__When to move to semver__

I'd like to see a move to semver in the near future, but I think that 3.2 needs to be released and then we can look at following the model Firefox implemented when they moved from their 3.6 to the new versioning (4 and up). 3.6 was kept running with long term support whilst the other versions lept on. I think, for the benefit of developers that are running SS3.1 and want to upgrade to 3.2 we'll need to support 3.2 with no semver for a decent period of time whilst also moving forward with semver releases side-by-side, this will allow people to keep recieving security patches and minor feature updates on their 3.2 projects without abandoning them completely.

__Other implications__

Moving to semver means that we'll see a (relatively) massive acceleration in version number increments with new versions likely to be released 2 or 3 times a year (see 

further down about release schedules) and this will have implications for clients and developers depending on what support commitments (again see further down) are made by 

SS.

Apologies in advance if there are (internal or external) decisions already made in regards to release schedules and support/EOL commitments.

**Release schedules**

With semver there's the scope for version numbers to skyrocket (by releasing every change that's made every week or so and back/forward porting the patches) as well as major 

and minor releases probably being just as frequent. This isn't a managable or realistic approach and so I think there needs to be a sensible and predictable release schedule.

Here's Drupal's: https://www.drupal.org/node/2135189

They go for a new major version every 2 years and a minor version every 3 months. Wordpress is similar. Ubuntu do a new release every 6 months which usually results in new major version every year.

Personally, for SS, I think this is a little infrequent, but that's just me.

Things to be defined:

 - Patch release schedule (as they come or at set intervals?)

 - (Minor) Feature release scheduldes

 - (Major) Breaking release schedules

**Support commitments**

Because of the accelerated version increments and breaking changes, it'll be valuable to large clients, agencies and developers to have predicatable and guaranteed support periods including long term support (LTS) versions of SS.

LTS is something that Ubuntu and Drupal also do (https://wiki.ubuntu.com/LTS). It provides certainty to larger clients that are security and stability focused to know that they can pick an LTS version and they won't be "forced" into an early upgrade because EOL is only a year or two after release.

LTS is tpyically *years* after release, where as support for non LTS may only be months. (4 or 5 seems to be Drupal and Ubuntu's preference).

There's been some casual mention that work won't be merged back; this policy needs to be defined and clear and definitely shouldn't be the case for LTS releases.

Things to be defined:

 - Will there be LTS versions? If so, what's the release schedule and support commitment

 - How long will ordinary versions be supported for?

 - What work will be merged back/forward and for how long?

**End of life plans**

How long will versions be supported for and when will they be retired? That's the main question and something that will provide clear guidence and certainty to developers and companies using SS. It'll give an idea of how frequently upgrades will be needed and whether it's worth holding out for the next LTS (if there is one) or stick with the last one.

Things to be defined:

 - EOL schedule for releases.

There we go, a lot to think about...

[James Cocker]

Semver is clearly the sensible way to go. However with a likely increase in SilverStripe releases, I'm wary of the potential extra workload required in keeping multiple SilverStripe sites up to date, and still working with all their required third party modules. 

As a developer of approximately 60 SilverStripe websites it's quite a job keeping them all up-to-date with the latest security releases, mainly due to the inconsistency around how third party modules are versioned. When a new SilverStripe release comes out, it's a nightmare to have to go through every module of every site and check which version works with the latest version of SilverStripe, as well as identifying whether the latest module version will require any updates to my code. Composer has made this a bit easier, but as not all modules do "releases", it can become quite a fragile mess.

So I just wanted to make sure that this is taken into account with any decision to go ahead with semver. So that improvements can be made to the upgrade process, and a strict set of rules about how third party modules should be versioned and updated is not just finalised, but is actively enforced. 

As advice for module developers is likely to updated for any proposed changes in SilverStripe versioning, I think this would be a good opportunity to also lay down some stricter rules that when implemented by all module developers will make maintaining and upgrading multiple SilverStripe websites that rely on several modules much less risky.

James

[Hamish Friedlander]

@Daniel, if a team self-assembles and volunteers to support an LTE version, I have no problem with them doing that, although I personally wouldn't pick 3.1 / 3.2 to do that with. I don't think we can add extra work to the existing core team though. While additional community support might appear, it's safer for planning to assume that won't happen, and that things will continue to operate roughly as per current: The latest major release continues to get new features, the latest minor release and the previous major release continue to get bug fixes, and every other major / minor release gets security fixes (or is declared "unsafe, upgrade to minor release X") for about 18 months.

@James, there's no method for *enforcing* any standard on module developers, nor would I want to. I think we'd want to say it's a SilverStripe coding convention that modules follow Semver, and one of the requirements for being on any list of recommended modules would be following SilverStripe coding conventions, but that's as far as I'd go. Following Semver in core should make upgrades easier though, and I can't really see any way it'll make things worse. Though there would be more frequent major releases, those releases already happen, they're just (BC breaking) minor releases instead, and more frequent patch releases shouldn't be an issue because they'd always be BC.

Hamish Friedlander

 

[Daniel Hensby]

@Hamish: LTS versions really depend on how often releases are going to be and what kind of structure there will be. If there's no true roadmap or schedule for releases, then we could find major releases being so frequent that it's incredibly difficult to have a stable version. So this is more a planning issue, really.

@James: Hamish has this right, I don't think moving to semver will make things worse, the problems you raise are ones that exist now, in fact, to a much worse extent as you will never no if "patch" changes will be breaking or not, minor releases always are, and so on. So you must have those problems now whenever there's a release.

Module devs will need to make sure that they are defining their version requirements correctly, and that will always be the case. Ultimately, the work involved in upgrading and testing a site will always lie with the person that is paid or has the responsibility of maintaining it, not the OS community.

--
You received this message because you are subscribed to a topic in the Google Groups "SilverStripe Core Development" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/silverstripe-dev/J4U4Nl2qTSg/unsubscribe.
To unsubscribe from this group and all its topics, send an email to silverstripe-d...@googlegroups.com.

[Sam Minnée]

We need to make some decisions pretty quickly about 3.1, 3.2, and 4.0. I think the LTS discussion is interesting but kind of a distraction from short-term concerns.

Are there any objections to :

 1. Branching 3.2 off now, and avoiding any documented API breakages from 3.1 -> 3.2, which may involve some commits to 3.2 that don't get merged back to master.

 2. Updating composer.json so that 4.0.x-dev is an alias for master.

 3. Merging any features changes into the 3.2 branch rather than the 3.1 branch from here on out?

Thanks
Sam

[Damian Mooyman]

@Sam the only thing I'd change about this is the branching of 3 instead of 3.2, and instead branch 3.2 from this once we accept this as feature complete (when we do 3.2.0).

I would prefer "semantic versioning from 3.2 onwards" rather than "semantic versioning from <date>".

Damian Mooyman | Senior Platform Developer

SilverStripe

http://silverstripe.com/

Phone: +64 9 281 3498

Skype: tractorcow

--

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.

[Loz Calver]

I would prefer "semantic versioning from 3.2 onwards" rather than "semantic versioning from <date>".

Is it then a bit unclear which branch new features should target (3.1 or 3)? If we say 3 only, then we may as well just semantic versioning start now. If we don’t say 3 only, it’s more work to merge features upstream, right?

When this is done, should the default branch be changed to master too? As per the discussion in https://groups.google.com/forum/#!topic/silverstripe-dev/dNqGmhO9J28

[Damian Mooyman]

We could alias 3 as 3.3.x-dev and simply clarify no new features should be put into 3.1 or below.

[Sam Minnée]

OK, let's try that again... ;-)

Are there any objections to :

 1. Branching "3" off now, and avoiding any documented API breakages from 3.1 -> 3.2, which may involve some commits to "3" that don't get merged back to master.

 2. Updating composer.json so that 4.0.x-dev is an alias for master.

 3. Merging any features changes into the 3 branch rather than the 3.1 branch from here on out?

——

There are some secondary actions that aren't actually immediate, but good for context:

 4. Branching off 3.2 once we're comfortable that we've got no more feature to add to 3.2, which I would suggest happens before christmas.

 5. Releasing our first beta release at the same time as creating the 3.2 branch

Thanks,
Sam

[Damian Mooyman]

That sounds good to me Sam.

--

[Jonathon Menz]

Hi all,

I've been trying to update a couple of my modules to use semver but wanted to check best practice. If I understand it correctly then semver dicates that minor releases can contain new features but must be backwards compatible. That means to me that for most modules (maybe not CMS and Framework) you would only need one branch for each major version, named e.g. '1.x', '2.x' etc. 

Does that make sense? That's the conclusion I came to but the latest SS blog post seems to imply that the yet to be released 1.1 branch of Subsites will be compatible with SS3.2, therefore maybe not backwards compatible to SS3.1? Wouldn't that justify a 2.x release?

On Friday, 17 October 2014 07:12:27 UTC+10:30, Hamish Friedlander wrote:

Hi Everyone,

Something that came up again in the discussion around namespacing at https://github.com/silverstripe/silverstripe-framework/issues/3548 is that SilverStripe doesn't currently follow the principles of semantic versioning (http://semver.org). 

While there are both historical and technical reasons for that, we’re not really tied to the current versioning semantics by anything except inertia, so it’s worth examining if we want to adopt semantic versioning as a new standard.

Right now, our versioning semantics are something like this:

 - Point release: bug fixes and minor changes that don’t substantially affect user experience

 - Minor releases: only include changes that can be resolved easily by developers, e.g. through the execution of a tool or by following a few clearly-defined steps

 - Major releases: significant refactoring might be required

Semantic versioning is described fully at http://semver.org, but is roughly:

 - Point release: bug fixes, no new features

 - Minor releases: new features/APIs, but no compatibility-breaking changes

 - Major releases: significant redacting might be required

If we switch to adopting semantic versioning, then our version scheme won’t distinguish between “some small changes are required” and “major changes are required”, which our historic versioning scheme as done.

There will be some other effects of moving to semantic versioning:

 - Once a minor release is out, point releases must only contain bugfixes. All new features will need to wait for the next minor release.

 - There is likely to be more frequent minor releases

 - There is likely to be more frequent major releases

 - More frequent releases means existing releases will be end-of-lifed faster

 - It will be clearer what versions of SilverStripe a module will work with

Specifically, it’s likely there wouldn’t be a 3.2 release, and there would be a 4.0 instead. 3.1 would move into security-fixes-only support mode about 6 months after that release.

In order to mitigate the effect of more frequent backward-compatibility-breaking changes, we would introduce a new open source commit policy around providing more assistance for upgrading between major versions. It might be something like this:

“For any API change, one of the following must be provided, in order of preference:

A script that transforms project/module code to suit the new API

A script that identify potential areas that need to be fixed

A section in the upgrade guide that explains the changes that need to be made”

So, what do people think? Should we shift to using semantic versioning?

Hamish Friedlander

[Conrad Dobbs]

It would be good if there was some sort of release name, or external versioning to make communicating to clients easier around major releases (e.g current version 2 to version 3). 

[dam...@silverstripe.com]

Hey guys, here's a quick update on where we are at.

We have branched master into a new 3 branch on each of the main repos (cms, framework, installer). This has been aliased as 3.2, where the master branch has been re-aliased as 4.0. This means you can already composer create-project a 4.0 project, not that you'll see anything there yet. :)

In the interest of ensuring the upgrade from 3.1 to 3.2 is painless, I've re-implemented my api-reversion PR at https://github.com/silverstripe/silverstripe-framework/pull/3704. This doesn't remove any of the new SQLSelect API (which is seemingly quite popuplar), but it moves the deprecation for SQLQuery up until 4.0, to be marked for removal probably in 5.0.

There are still breaking changes in this upgrade, but in the spirit of following semver we will try to reduce this to the minimum necessary breakage.

Also, since this introduction I've come across a rather annoying composer bug when trying to alias numeric branches. At the moment trying to require 3.2.x-dev doesn't work properly; The fix for this is at https://github.com/composer/composer/pull/3480 and awaiting approval.

Another next step is for us to update travis to now work with the new branches, and to update the database connectors to now respect the new versions available. (change the ~3.2 dependency on framework to >=3.2).

Kind regards,

Damian

[dam...@silverstripe.com]

Each module will have their own versioning, and won't necessarily follow semver. Maybe in the future, but at the moment we are only implementing this practice for framework cms and installer.

Ideally we will work towards versions of modules that work both with 3.1 and 3.2, if possible, rather than having to maintain separate branches, but it's likely inevitable that this will happen.

[Jonathon Menz]

Thanks for the feedback Damian. I think it would be great to establish a standardised branch and release structure for for all SS modules, just to keep things consistent and predictable when working with composer. This wouldn't need to be compulsory but it could be a best practice to be encouraged. Re: major versions, I meant of the module in question rather than the framework. For example on betternavigator I'm currently working on the 2.x branch and won't add anything new to the 1.x branch. Next time I want to change something that breaks compatibility I'll create a 3.x branch and stop adding any new features to the 2.x branch (but still add critical patches to the older branches). This workflow should hopefully mean people stuck on older versions of the CMS can always access a stable version of the module, it just may not be the latest version.

[Ingo Schommer]

I've tried to document what was discussed here on our release process: https://github.com/wilr/sapphire/pull/7

Pull request goes to Will'r docs rewrite fork for now, makes it easier to merge. Feedback welcome.

[Nick Fauchelle]

Good morning,

Is there an update on what has happened here?

It seems the 3.1 branch is now on feature freeze, but I can't see if that was decided on in here - just lots of proposals.

Has something been decided, whats the current process and where should things go?

Thanks

Nick

[Damian Mooyman]

Hi Nick,

Semantic versioning has now been officially adopted, meaning that indeed only bug fixes for 3.1 branch should be accepted now. Non-breaking features should go into the 3 branch, slated for release as 3.2 in the near future. Master (framework 4) is where any breaking changes can be made.

http://docs.silverstripe.org/en/contributing/release_process/

Kind regards,

Damian Mooyman | Senior Platform Developer

SilverStripe

http://silverstripe.com/

Phone: +64 9 281 3498

Skype: tractorcow

--
You received this message because you are subscribed to a topic in the Google Groups "SilverStripe Core Development" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/silverstripe-dev/J4U4Nl2qTSg/unsubscribe.
To unsubscribe from this group and all its topics, send an email to silverstripe-d...@googlegroups.com.