Sonata version management

[soullivaneuh]

@rande As we discussed, you said that branch management was failed and should be reviewed.

So I decide to make a proposal about this.

I make it as an issue on SonataAdminBundle cause this is the most viewed repositories and any contributors feedback would be appreciated.

Versions tags and branches

We should enable a road-map for repositories versions. This will help a lot user to know which version to install and contributors to know where they must propose their PR.

Versions schema

I propose the following schema:

• nightly: The next major release. Not stable yet.
  • Would be master on most cases.
  • New features and/or BC break modification must be proposed here.
• stable: The currently stable version of the package.
  • Fixes should be proposed on this branch.
• legacy: Old but stable release.
  • Just here to tell people they should upgrade to the next release.

Here, a example table with some sonata packages, based on next stable release (e.g. 3.0 for admin):

Sonata package	nightly	stable	legacy
admin-bunble	4.0	3.0	2.3
core-bunble	4.0	3.0	none
seo-bunble	4.0	3.0	1.1
cache-bundle	4.0	3.0	2.1
exporter	1.4	1.3	1.2

Feel free to add package you think important by comment, I'll merge it on this table. 👍

Branching

Starting new stable version, the branching system should be done like Symfony team does:

• Write/Merge new feature on nightly
• Write/Merge bugfixes on stable
• Merge stable onto nightly when stable is updated.

Version tagging

For stable, each bugfixes should be tagged as a new patch version. Obviously, is many bugfixes PR are waiting and could be easy picked, wait for them before push a new patch tag.

For nightly, push a new stable tag only when the version seems to be ready. When it's done, nightly will become the new stable etc...

Backward Compatibility

All minor tags (e.g. 1.2 => 1.3) MUST be BC according to semver: http://semver.org/

If someone propose a PR with BC break that cannot be resolved, let's wait for the new major release.

Changelog file

I propose to specify which version is related to the changelog message.

Here a sample: https://github.com/Soullivaneuh/IsoCodesValidator/blob/master/CHANGELOG.md

Milestones

I think milestones should be used at least for next version preparing. We can start by opening a 2.4 milestone for SonataAdminBundle in example.

This will drastically simplify issues and PR management. In addition, if a BC breaking PR is coming and new major version is not for now, this could be added onto a milestone too.

Thanks for reading 👍

Hope I'm enough clear and my English not so much bad. 😄

Any another idea or section I'm perhaps missing?

I'll updated this RFC along the discussion.

When this document will be enough mature, I'll make a PR on SonataAdminBundle first as an experiment with contributing documentation update and start milestones / branch management. Another package should be updated next.

Regards.

[nlzet]

I think this is a great idea and it is something that is currently missing indeed. In my opinion a lot of people are currently having trouble with Sonata due to missing knowledge about bundles and versions they can/should use.

I do have some questions/ideas about some things in the proposal:

• When a new branch will be released in a bundle, does that mean all bundles will get a new version ? For example in Symfony all split-bundles are released in a new branch simultaneously. (2.6, 2.7)
• When this branching idea will come to a start, will all bundles get a new branch as a start reference point? (e.g. 3.0)
• Depending on the answer on both previous questions, is it an idea to put all bundles in the same version number (e.g. 3.0), and from then on release everything together? (3.0, 3.1, ..)

[soullivaneuh]

@nlzet very goods questions! I'll try to make the best answers. Maybe @rande can complete me.

When a new branch will be released in a bundle, does that mean all bundles will get a new version ? For example in Symfony all split-bundles are released in a new branch simultaneously. (2.6, 2.7)

Actually no. Bundles are separated so if one of them has no need of new minor or major version, it will be left as is. As you can see in my table, versions are different across bundles actually.

When this branching idea will come to a start, will all bundles get a new branch as a start reference point? (e.g. 3.0)

Yes. Old not mergeable branches will be simply abandoned. But it wont necessary start with a new major version but with the next stable. In example, for SonataAdminBundle, the starting point will be on 2.4.

For bundle having stable version on not new minor/major version on progess, the current version will be the starting point. It's the case of SonataCacheBundle.

Depending on the answer on both previous questions, is it an idea to put all bundles in the same version number (e.g. 3.0), and from then on release everything together? (3.0, 3.1, ..)

Well, that's an idea. To be honest, I got the same for a while. But for doing that, we have to make the same logic as Symfony, e.g. moving all source code on one repository like sonata-project/sonata and make read-only repositories.

That will cost huge efforts and could be painful. BTW, I haven't enough knowledge of all sonata bundle to know if it's feasible.

I think we should leave this as is for the moment and start a new discussion with @rande about it when we'll got a stable branches and versions management.

[soullivaneuh]

Added a note about Changelog file.

[nlzet]

@soullivaneuh thanks for the response. All answers are pretty clear to me. For my last question, I understand this would be very hard and might not be interesting. (Even though I believe that this has many advantages too)

I do believe if we don't to this, we got to have a good documentation page about versions. When I started with Sonata, I guessed I had to use the same version numbers (2.3 with 2.3 or 2.4 with 2.4) where possible, while this is not always true and some bundles have entirely different version numbers.

How I believe this idea will go, there will be new versions of bundles sooner than before, which will mean it will be harder to know which versions work together. Or should you just only use stable/nightly/legacy bundles together, and don't mix them?

Also a small note, you have some typo's in this issue. It states a few times xxx-bunble

[jvasseur]

Composer should prevent you from installing incompatible versions, we just need to put correct constraints in the composer.json.

Synchronizing versions have some downsides like bumping some bundle versions when no change happens.

[soullivaneuh]

I understand this would be very hard and might not be interesting.

It's interesting. But have we have more urgent issue to solve at this moment: versionning.

BTW, some sonata package like exporter are not bundle and have a totally separate version.

As I said, this will be a good start for a another discussion IMO.

I do believe if we don't to this, we got to have a good documentation page about versions.

I agree. I'll propose it on a PR for SonataAdmin as a starting point.

How I believe this idea will go, there will be new versions of bundles sooner than before, which will mean it will be harder to know which versions work together. Or should you just only use stable/nightly/legacy bundles together, and don't mix them?

I don't understand the point of your question, sorry. :-)

[soullivaneuh]

Synchronizing versions have some downsides like bumping some bundle versions when no change happens.

Yes, I agree too.

[soullivaneuh]

cc @pulzarraider if you missed that. :-)

[nlzet]

@soullivaneuh,

I don't understand the point of your question, sorry. :-)

What I meant was, when there will be a nightly/stable/legacy version for each bundle. Does that ensure a user should use the same versions combined, or is it still possible to mix them.

Example bundles:

Bundle	Nightly	Stable	Legacy
AdminBundle	2.5	2.4	2.3
CoreBundle	2.4	2.3	none

Does that mean I can only use AdminBundle 2.5 with CoreBundle 2.4, or is it supported to mix the AdminBundle 2.5 with CoreBundle 2.3 (or any other combination of different types of stability).

[Brainshack]

You shouldnt really need to take care about this, since dependency management is what composer does for you. If you install the AdminBundle in Version 2.4, it will automatically install the required Version of the CoreBundle.

As for the general idea of this thread, you have my +1 :)

[soullivaneuh]

@nlzet

Does that mean I can only use AdminBundle 2.5 with CoreBundle 2.4, or is it supported to mix the AdminBundle 2.5 with CoreBundle 2.3 (or any other combination of different types of stability).

@Brainshack just answered right:

You shouldnt really need to take care about this, since dependency management is what composer does for you.

In addition, minor version should not be BC break, so you'll be able to upgrade easily.

As for the general idea of this thread, you have my +1 :)

Thanks! :-)

[nlzet]

Ok thank you for these answers, it's clear to me now

[adamquaile]

👍 I completely agree that there needs to be a proper strategy for versioning and updates. IMO the most important things are that each bundle is separately versioned and follows semver, with proper dependency declaration, allowing composer to deal with everything else.

A couple of questions / comments:

I propose the following schema

By nightly, stable, legacy, what are we referring to? Branches, tags, or just notes on a readme / roadmap. I'd say the latter. I'd use branches for each maintained version.

New features and/or BC break modification must be proposed here [nightly]

I'd say that features which don't break BC could be applied to an older version, and merged through the later versions. Symfony does this

All bug fixes merged into maintenance branches are also merged into more recent branches on a regular basis. For instance, if you submit a patch for the 2.3 branch, the patch will also be applied by the core team on the master branch.
https://symfony.com/doc/current/contributing/code/patches.html#step-2-work-on-your-patch

But overall, yes, a massive 👍 for this - it's desperately needed.

[soullivaneuh]

By nightly, stable, legacy, what are we referring to?

A note on the README. Generaly, master branch for nightly and one branch per minor version.

I'd say that features which don't break BC could be applied to an older version, and merged through the later versions.

Exactly, but on a minor (e.g. 1.X), not a patch (e.g. 1.0.X).

[adamquaile]

@soullivaneuh Great! Then I agree.

This would also massively simplify the installation process to composer create-project sonata-project/sandbox.

[pulzarraider]

👍 for clear specification of version managment.

[dbu]

+1
i think in the description about bugfixes, you should say "patch", not "minor".

and it would be great to be more careful about semver. the changes between SonataAdminBundle between 2.3 and 2.4 are so big, e.g. jquery inclusion and the base admin classes method signatures changes alone would imho have been enough for calling it 3.0.

there should not be a new major version every 3 months, but if its needed, lets not hesistate to do one. otherwise keep BC and record issues for the next major version

[soullivaneuh]

i think in the description about bugfixes, you should say "patch", not "minor".

I which part?

the changes between SonataAdminBundle between 2.3 and 2.4 are so big, e.g. jquery inclusion and the base admin classes method signatures changes alone would imho have been enough for calling it 3.0.

Agree. But I think this is too late for 2.3. We will make a good start with 2.4.

there should not be a new major version every 3 months, but if its needed, lets not hesistate to do one. otherwise keep BC and record issues for the next major version

This is exactly why I proposed milestone usage. 👍

[virtualize]

+1 thanks for bringing this up

[dbu]

this one:

Version tagging

For stable, each bugfixes should be tagged as a new minor version. Obviously, is many bugfixes PR are waiting and could be easy picked, wait for them before push a new patch tag.

[soullivaneuh]

@dbu Indeed. Was a mistake.

It's fixed now, thanks. 👍

[adamquaile]

Is this proposal accepted? If so, what are our first steps? Should we open an issue / PR for each of the bundles to ensure they all declare their dependencies correctly?

If not, what do we do to make it happen? It would be a huge improvement to sonata in general.

[soullivaneuh]

Is this proposal accepted?

Not yet, I have to talk about it with @rande.

If so, what are our first steps? Should we open an issue / PR for each of the bundles to ensure they all declare their dependencies correctly?

I'll open a first PR on sonata-admin for tests and discussion. Next, I'll apply it on all bundles. Maybe a common repositories for contribution doc would be nice too.

[adamquaile]

Okay, thanks. Yeah, some kind of doc to organise it all would be useful in letting people know how they can help move it forwards.

[soullivaneuh]

We are almost here! 🎉

All packages are now updated except 3 of them.

I closes this one in favor of dev-kit one: sonata-project/dev-kit#140

Thanks all for your support about this new adventure! 👯 😃