Sonataadminbundle: 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. :+1:

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 :+1:

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

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]

:+1: 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 :+1: 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]

:+1: 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. :+1:

[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. :+1:

[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]

@rande After some search, I think 2.3 branch of admin-bundle is merge-able quite easily.

What do you think? Could work on it.

[mmeloni]

+1.
We are fully agree on that goal . We spent a month trying to install the latest version and then switch to the stable without success . Only with the sandbox we succeeded. A modular installation is a nightmare. .

[Th3Mouk]

Hello everyone this is my return after 2 years of use of Sonata.

Today i have more than ten website in production with this collection of bundle.

The major problem is i can't afford to base my productions on the admin 2.4 branch cause is still in development.

My favorite part is Page/Block bundles IMO are killers feature.

This is the last stable build that i can't make :

sonata-project/admin-bundle              2.3.5              Symfony SonataAdminBundle
sonata-project/block-bundle              2.2.13             Symfony SonataBlockBundle
sonata-project/cache                     1.0.6              Cache library
sonata-project/cache-bundle              2.2.4              This bundle provides caching services
sonata-project/core-bundle               2.3.8              Symfony SonataCoreBundle
sonata-project/datagrid-bundle           dev-master cc42f28 Symfony SonataDatagridBundle
sonata-project/doctrine-extensions       1.0.2              Doctrine2 behavioral extensions
sonata-project/doctrine-orm-admin-bundle 2.3.2              Symfony Sonata / Integrate Doctrine...
sonata-project/easy-extends-bundle       2.1.9              Symfony SonataEasyExtendsBundle
sonata-project/exporter                  1.4.0              Lightweight Exporter library
sonata-project/formatter-bundle          2.3.3              Symfony SonataFormatterBundle
sonata-project/google-authenticator      1.0.2              Library to integrate Google Authent...
sonata-project/intl-bundle               2.2.3              Symfony SonataIntlBundle
sonata-project/media-bundle              2.3.3              Symfony SonataMediaBundle
sonata-project/notification-bundle       2.3.2              Symfony SonataNotificationBundle
sonata-project/page-bundle               2.3.9              Symfony SonataPageBundle
sonata-project/seo-bundle                1.1.10             Symfony SonataSeoBundle

The first embarrassing think is that i had to fork SonataUserBundle and freeze it to keep stability with my application (due to block BC).

The second is then a correction is made on 2.3 branch (that is stable) of SonataBlockBundle i can't get it because SonataPageBundle force to keep the last 2.2 version. And the master branch is on 2.4.

I gotta feeling (ouuu ouuuu :microphone:) that legacy branch are abandoned (like last SonataUser releases or 2.2 Block) while they make part of last stable build, and all dev are focus on master branch.

The major problem of this, is still the confusion between new feature on masters branch, and inclusion of some of them in legacy stable release.
Which bring us to the conclusion, if we want corrections on old stable version, we can merge it, but they are mixed with new features require link to other bundles on master branch, or bug fixes are directly merged on master and not accessible.
For example a modification on master (2.4) admin bundle may result corrections on block bundle but instead of merging it on master (2.4) branch it is subject to a version 2.3.8. It's an exemple.
That is not recommended for production and my team which is not necessarily able to quickly correct problems that arise in sonata bundles collection from a deal with composer update.

Actually when I find a problem, I try to resolved it on PR, but the last the solution i have is to freeze my versions while the release of 2.4 stable pack.
Is it planned to review how to manage and determine PR goals and branch ?
My employer does not leave me time to help, i'm very limited on my PR.

I hope it will bring you a different perspective.

Cheers :beers:

[rande]

@Th3Mouk Thanks for the feedback, it is very welcome. The 2.4 branch has been in dev mode for too long, and actually it is quite stable. We plan to release a tagged version for bundles very soon. So you can upgrade your projects with the latest versions. @Soullivaneuh also try to provide a new strategy for releases management, hope it will solve issues you expose.

[OskarStark]

any news about a new stable version?

[soullivaneuh]

@OskarStark Some issues need to be resolved before: https://github.com/sonata-project/SonataAdminBundle/milestones/2.4

[core23]

Is there any roadmap when we can expect the next mayor version for the sonata projects? I wrote some pr's for new features in the last months but it seems that everything would become a bc break for now.

Today every change in an Interface would resolve a break. As mentioned in https://github.com/sonata-project/SonataSeoBundle/pull/106 I like the symfony approach http://symfony.com/doc/current/contributing/code/bc.html. You could add interfaces in minor version, if you change non-api files and leave a hint in the UPGRADE file. What do you think about it?

[pulzarraider]

As I mentioned in the sonata-project/SonataCoreBundle#191. New branches should be created ONLY if the next version contains some BC breaks. So if no BC break is created, no new branch is needed.

The minor versions (e.g. 2.x) should be released more often. Nice exmaple of this release process is Twig.

@core23 the 2.4 shoud be finished first. After that we can talk about 3.0.

[core23]

@pulzarraider I agree that minor releases should come more often. But are you sure that BC breaks are allowed in minor version? According to http://semver.org @rande and @Soullivaneuh say that no BC breaks are allowed.

When I see the open issues and pull requests... that should be a long way to the next big major release. I would like help you to reduce the amount of tickets. Maybe you could add me as a contributor to resolve some of the long enduring issues? @rande

[core23]

Refs https://github.com/sonata-project/SonataCoreBundle/issues/229

[ju1ius]

+100 for having a single repo for all the bundles ! This would ease contribution A LOT !
You don't even need to use git subtrees, see the babel repo.

[jvasseur]

@ju1ius the subtree-splits are needed for composer.

[greg0ire]

@ju1ius the subtree-splits are needed for composer.

More info on that : https://github.com/composer/composer/issues/1875

[ju1ius]

the subtree-splits are needed for composer.

Would @beberlei's fiddler be of any help ?

[greg0ire]

Not sure this matches our use case -__-

[greg0ire]

Another related issue : https://github.com/composer/composer/issues/914

[soullivaneuh]

I'm not a big fan of the "One repo for everything" because even if every component could be installed alone, each one will have a new version tag with no modification because not concerned.

We have a lot of tiny bundles for very special things. Take Symfony acl part for example, this one is now out of the main repo AFAIK.

BTW, we are discussing to have 2.x branch with new tag system right now. Changes are coming soon.

[soullivaneuh]

Please see https://github.com/sonata-project/dev-kit/pull/1.

[ju1ius]

For future reference, a few resources about pros/cons of the monorepo pattern:

• Dan Luu
• Gregory
• Face book
• Benjamin Pollack
• Benjamin Eberlei
• Digital Ocean
• Google
• Twitter
• thedufer
• Paul Hammant

[soullivaneuh]

We are almost here! :tada:

All packages are now updated except 3 of them.

I closes this one in favor of dev-kit one: https://github.com/sonata-project/dev-kit/issues/140

Thanks all for your support about this new adventure! :dancers: :smiley: