New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Sonata version management #3053

Closed
Soullivaneuh opened this Issue Jun 11, 2015 · 44 comments

Comments

Projects
None yet
@Soullivaneuh
Copy link
Member

Soullivaneuh commented Jun 11, 2015

@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

This comment has been minimized.

Copy link

nlzet commented Jun 12, 2015

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

This comment has been minimized.

Copy link
Member

Soullivaneuh commented Jun 12, 2015

@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

This comment has been minimized.

Copy link
Member

Soullivaneuh commented Jun 12, 2015

Added a note about Changelog file.

@nlzet

This comment has been minimized.

Copy link

nlzet commented Jun 12, 2015

@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

This comment has been minimized.

Copy link
Contributor

jvasseur commented Jun 12, 2015

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

This comment has been minimized.

Copy link
Member

Soullivaneuh commented Jun 12, 2015

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

This comment has been minimized.

Copy link
Member

Soullivaneuh commented Jun 12, 2015

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

Yes, I agree too.

@Soullivaneuh

This comment has been minimized.

Copy link
Member

Soullivaneuh commented Jun 15, 2015

cc @pulzarraider if you missed that. :-)

@nlzet

This comment has been minimized.

Copy link

nlzet commented Jun 15, 2015

@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

This comment has been minimized.

Copy link
Contributor

Brainshack commented Jun 15, 2015

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

This comment has been minimized.

Copy link
Member

Soullivaneuh commented Jun 15, 2015

@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

This comment has been minimized.

Copy link

nlzet commented Jun 15, 2015

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

@adamquaile

This comment has been minimized.

Copy link
Contributor

adamquaile commented Jun 15, 2015

👍 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

This comment has been minimized.

Copy link
Member

Soullivaneuh commented Jun 15, 2015

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

This comment has been minimized.

Copy link
Contributor

adamquaile commented Jun 15, 2015

@Soullivaneuh Great! Then I agree.

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

@pulzarraider

This comment has been minimized.

Copy link
Member

pulzarraider commented Jun 16, 2015

👍 for clear specification of version managment.

Soullivaneuh referenced this issue in sonata-project/SonataDoctrinePhpcrAdminBundle Jun 16, 2015

require SonataAdminBundle 2.4 and TreeBrowserBundle 2.0, drop use of …
…SonataJqueryBundle (will require additional work to integrate bower)
@dbu

This comment has been minimized.

Copy link
Collaborator

dbu commented Jun 16, 2015

+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

This comment has been minimized.

Copy link
Member

Soullivaneuh commented Jun 16, 2015

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

This comment has been minimized.

Copy link
Contributor

virtualize commented Jun 16, 2015

+1 thanks for bringing this up

@dbu

This comment has been minimized.

Copy link
Collaborator

dbu commented Jun 17, 2015

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

This comment has been minimized.

Copy link
Member

Soullivaneuh commented Jun 17, 2015

@dbu Indeed. Was a mistake.

It's fixed now, thanks. 👍

@adamquaile

This comment has been minimized.

Copy link
Contributor

adamquaile commented Jul 13, 2015

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

This comment has been minimized.

Copy link
Member

Soullivaneuh commented Jul 13, 2015

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

This comment has been minimized.

Copy link
Contributor

adamquaile commented Jul 13, 2015

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

This comment has been minimized.

Copy link
Member

Soullivaneuh commented Jun 6, 2016

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! 👯 😃

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment