search

plone / plone.restapi

RESTful API for Plone.
http://plonerestapi.readthedocs.org/
84 stars 72 forks source link

plone.restapi 9 #1683

Closed tisto closed 8 months ago

tisto commented 9 months ago

ToDo

Schedule

Tickets

Pull Requests

tisto commented 9 months ago

@plone/release-team I plan to cut a plone.restapi 9 release soonish. Technically it will be a breaking change release. Though, Volto 16 and 17 are already prepared to work with the changes. Therefore it should not break anything and we could include it in Plone 5.2 as well. I'd recommend that we start using plone.restapi 9 in Plone 5.2 and 6.x from now on. I do not plan to support plone.restapi 8 and 9 together. plone.restapi 7 will remain the release where we backport stuff.

I also plan to switch the default branch from master to main. Do you see any problems with this? I will prepare PRs for buildout.coredev 5.2 and 6.x.

stevepiercy commented 9 months ago

I also plan to switch the default branch from master to main. Do you see any problems with this? I will prepare PRs for buildout.coredev 5.2 and 6.x.

Not a problem, but a few tasks. We would need to update automation that builds docs on RTD, possibly Netlify preview, and pulls in the submodules into the main documentation.

tisto commented 9 months ago

@stevepiercy I used the "rename" functionality in github. I think main took over all attributes of the master branch. Feel free to double-check.

davisagli commented 9 months ago

Therefore it should not break anything and we could include it in Plone 5.2 as well. I'd recommend that we start using plone.restapi 9 in Plone 5.2 and 6.x from now on.

@tisto The versions.cfg for Plone 5.2 currently includes plone.restapi 7.8.2. I think it would be surprising and too big a change to update it to plone.restapi 9. But, we can say in plone.restapi's readme that we recommend plone.restapi 9 for use with Plone 5.2 as well

stevepiercy commented 9 months ago

I think that about covers docs.

mauritsvanrees commented 9 months ago

Plone 5.2 must indeed stay on plone.restapi 7.x.x, as it is the last release compatible with Python 2. I once thought about defining separate versions for Python 3, like we do for several external packages, but I did not want to do this for core Plone packages.

For Plone 6.0 I would very much prefer to stay on plone.restapi 8, and let 6.1 use plone.restapi 9. By moving to version 9, we count on no one outside of Volto using the @linkintegrity, @unlock, @refresh-lock, and @tiles endpoints. It looks like collective.exportimport is not using it, so that is a start. I suppose that there is a fair chance that no one else is using them, but this is the kind of change that we try to avoid in a bugfix release of Plone.

I am not the one doing the main maintenance on plone.restapi though, and I can't press others into volunteering to support another plone.restapi branch. Still, I am tempted to create an 8.x.x branch (should be there anyway) and use this in coredev 6.0.

You wrote:

Volto 16 and 17 are already prepared to work with the changes.

The latest versions of these Volto series do not require these changes, right? They still work fine with current plone.restapi 8, and so will upcoming bugfix and even feature releases of Volto 16 and 17. Is that correct?

So can't we do the same as for Plone 5.2, where Volto has a KGS? By default Plone 6.0.x backend keeps shipping with plone.restapi 8, and if you know you want plone.restapi 9, there will be a small list of package versions (probably just one) that you should update in your setup. I could even add the latest version in the release notes, just like I mention the current latest Volto version there.

BTW, a major release of plone.restapi would be a logical moment to drop Plone 5.2 support. This reduces the maintenance burden.

davisagli commented 9 months ago

Still, I am tempted to create an 8.x.x branch (should be there anyway)

@mauritsvanrees This is already planned in the checklist in this ticket (regardless of the question of which one to use for Plone 6.0)

BTW, a major release of plone.restapi would be a logical moment to drop Plone 5.2 support. This reduces the maintenance burden.

We still consider supporting both Plone 5.2 (on Python 3) and 6.0 in parallel an important goal for plone.restapi. There are still migrations in progress from older versions of Plone using the API.

mauritsvanrees commented 8 months ago

I have created branch 8.x.x. Also released 8.43.2 from this, adding missing changelog entries from 8.43.1. Coredev 6.0 now uses 8.x.x, and upcoming Plone 6.0.7 will use plone.restapi 8.43.2.

tisto commented 8 months ago

@mauritsvanrees I really would like to avoid having to support three different branches of plone.restapi (7,8 and 9). plone.restapi takes semantic versioning very seriously and therefore we will often have major version bumps. The difference between 8 and 9 is minimal and it is unlikely that it breaks anything. Most changes we do in minor versions of Plone have a far higher chance of leading to a problem than this version bump. Therefore I'd strongly suggest dropping plone.restapi 8 and moving on to plone.restapi 9 (for all Plone 6 versions, Plone 5.2 can stick with plone.restapi 7).

In the end this is your call. Though, I do not plan to put any effort into the 8.x branch and I do not have the capacity to support this version any longer. As soon as 9 is out, 8 should go into security fixes-only mode. This is why I did not create a 8.x.x branch to not let people jump to wrong assumptions.

sneridagh commented 8 months ago

@tisto totally agree on that. As long as we state this properly (somewhere) creating a 8.x.x branch is not a big deal, from my point of view, but we have to communicate this in an effective way.

mauritsvanrees commented 8 months ago

I am going to think about this a bit more, also in light of our discussion this afternoon.

Meanwhile, let me repeat my question. You wrote: "Volto 16 and 17 are already prepared to work with the changes." The latest versions of these Volto series do not require these changes, right? They still work fine with current plone.restapi 8, and so will upcoming bugfix and even feature releases of Volto 16 and 17. Is that correct?

tisto commented 8 months ago

@mauritsvanrees yes, to all your questions. Whenever we have a breaking change we try to write Volto core code in a way that it works with all supported versions of plone.restapi (in our case 8 and 9 and most likely 7 as well). The latest versions of Volto indeed do not require those changes.

If we would have a tight coupling between plone.restapi and Volto this would be a bigger issue and in that particular case we would rather wait for a major Plone release. Though, so far we could always work around this.

The upcoming plone.restapi 9 release is just called 9 because we take semantic versioning very seriously. :)

mauritsvanrees commented 8 months ago

I am trying to take semantic versioning serious in Plone 6.0.x as well, which is why I was a bit hesitant to include restapi 9. :-)

But you are the Release Manager for plone.restapi, and know this package better than I do. For example one of the PRs you point to that landed in 9 is about refactoring the lock endpoint. That sounds like this works differently than in 7 and 8, so people may need to adapt. But I see that the refactoring work is also in 7 and 8. The only difference in 9 is that the old deprecated way is removed. So there is less of a problem.

When it comes to pure ClassicUI packages like mockup/staticresources/barceloneta, I trust people like @petschki and @thet to make the right decision on what version should be included in 6.0.x. So I should trust you the same way for plone.restapi.

In light of our discussion last week, we want to support 6.0.x for a long time yet, so it should use a version that we are able and ready to support.

So: yes, let's use plone.restapi 9 in Plone 6.0.x.

But please wait a bit with making a release. In the Plone 6.0.7 that I wanted to release yesterday already, we will be using restapi 8 still. restapi 9 can be for 6.0.8.

tisto commented 8 months ago

@mauritsvanrees yes, we always first deprecate an endpoint or functionality, then remove it in Volto, and then drop it on the next major release. Basically the idea is that latest plone.restapi and latest Volto version will always work well together.

I am ok with waiting with the release. Let me know when you want me to push the button. I can make a plone.restapi 9.0.0 release any time.

wesleybl commented 8 months ago

We still consider supporting both Plone 5.2 (on Python 3) and 6.0 in parallel an important goal for plone.restapi. There are still migrations in progress from older versions of Plone using the API.

@davisagli are you afraid that content exported with plone.restapi 7 will not be imported with plone.resapi 9? Does keeping plone.restapi 9 compatible with Plone 5.2 really guarantee this? When would be the best time to drop support for Plone 5.2?

davisagli commented 8 months ago

@wesleybl We continue to add new endpoints to plone.restapi (such as @relations recently). If we keep plone.restapi 8.x compatible with Plone 5.2 then it is possible to use these endpoints in a migration from Plone 5.2 to Plone 6.

At least, that is my understanding of the reasoning. Personally I think it is more of a theoretical argument; I would be happy to drop support for Plone 5.2 and then consider backporting specific features if someone actually needs it. But, maybe I'm also forgetting part of the argument...

wesleybl commented 8 months ago

@davisagli what you said is true. But it will always be true. So we have to have a cutoff line. From 8 to 9 would be a good cut. The problem is that Volto 17 still supports Plone 5.2. Will this be the case until the end of Volto 17? Is Volto 17 for Plone 6.1? So would we have to have a version of restapi compatible with Plone 6.1 and 5.2?

tisto commented 8 months ago

@davisagli @wesleybl I do not plan to support plone.restapi 8 when plone.restapi 9 is out. plone.restapi 9 will still support Plone 5.2 and Plone 6 (and Plone 6.1).

If we take semantic versioning seriously, we will always have major version bumps and we have to move on. It does not make any sense in my opinion to continue to support plone.restapi 8. There is a very tiny chance that it might make sense to stick with plone.restapi (if you have a custom-made frontend app that relies on that particular tiny breaking change that the release introduces). Though, this is a 0.01% use case IMHO and fixing this in a custom app would be trivial.

I see a major communication problem within the Plone community though. People are so used to the "old way" of doing releases (breaking in minor versions, supporting all versions at the same time) that the expectations do not match with what you do when you follow semantic versioning (doing major version bumps and dropping support for old versions).

As release managers and as a community we just can not follow semantic versioning and do frequent major version bumps and at the same time support multiple branches.

cc @mauritsvanrees @sneridagh

tisto commented 8 months ago

@mauritsvanrees FYI: plone.restapi 9.0.0 has been released:

https://pypi.org/project/plone.restapi/9.0.0/

I updated buildout.coredev 6.1 and 6.0.