Branching strategy, Flex, 3.0.0 upgrades and conflicts

[yguedidi]

Hello there!
I'm in holidays and I have some tech time to invest!
I'd like to help making Wallabag advance toward 3.0.0 and latest PHP/Symfony 🙂

Current situation:

• latest version is 2.6.2
• Symfony 4.4
• min PHP 7.4
• master branch is the only active branch, so master branch is about 2.6.x
• one bugfix and one feature in next 2.6.x milestone (2.6.3)
• many things planned in 2.7.0 milestone
• from Upcoming wallabag version 3.0.0 & 2.6.0 #6177 Symfony 5 then 6 + PHP 8.0 then 8.1 + Flex are planned in 3.0.0

My supposed target situation:

• at least 2 active branches, one for active development, others for maintenance. to avoid situations like Add command to clean pictures path when changing instance URL #6655 (comment) 😅
• start the work on 3.0.0 as soon as possible to benefit from PHP and Symfony new features
• improvements to maintenance branches must be carefully merged in active branch by maintainers, so would be good to avoid doing that often or have it complex to resolve conflict
• continue delivering on new features

My conclusions:

• stale PRs are evil! we should avoid having PRs ready waiting for merge, so there must be branches in which they can be merged.
• the move to Flex is challenging, because it's the single big change that makes having an active branch for 3.x and maintenance branches for 2.x in parallel very complex, as it changes the file structure and organization.
  And merging new things from 2.x like bugfixes and new features to 3.x will certainly conflict a lot and be hard to do.
• because of above point, I think there are 2 ways to solve it: either we pause new features and deliver on 3.0.0 first, either we postpone the move to Flex.
• I'd vote for postponing Flex as the path to 3.0.0 with Symfony 6 can take a lot of time, in which it's not acceptable to pause working on new features and bugfixes IMO
• also, even if @j0k3r did an amazing work in Move to Symfony Flex  #6169, it's not really reviewable and rebasing or merging new changes will be tedious.
• finally, Flex structure is optional, we could move to latest Symfony 6 without Flex new structure
• side note: upgrade to Symfony 5 is doable now without waiting for the BC breaks as it require PHP 7.4

My proposal:

• release soon 2.6.3 with the feature and the bugfix
• create a maintenance branch 2.6 on top of 2.6.3, for bugfixes only
• make the master branch correspond to 2.7.x thanks to a branch alias, so that new features can be merged there
• optional: take the opportunity in 2.7 to upgrade to Symfony 5 there (part of Drop PHP < 8.0 + Symfony 5 upgrade #6052)
• optional: take the opportunity in 2.7 to upgrade to Symfony 6 there (part of Drop PHP < 8.1 + Symfony 6 upgrade #6051)
• optional: take the opportunity in 2.7 to upgrade to PHP 8.0 (part of Drop PHP < 8.0 + Symfony 5 upgrade #6052)
• optional: take the opportunity in 2.7 to upgrade to PHP 8.1 (part of Drop PHP < 8.1 + Symfony 6 upgrade #6051)
• optional: if we really want Flex as soon as possible, create a dev branch next or 3.0 to start the work on Flex, by small reviewable PRs, and frequently merging and adapting changes from 2.7

What do you think?

PS: I'm about to start removing some Symfony 4.4 depreciation, I believe the corresponding PRs could be merged either in 2.6 either 2.7 without issues, up to you :)

[nicosomb]

I think it can be a good thing to move forward.

What is @j0k3r opinion about Flex?

just for your information, 2.6.3 will also contains 2 security fixes.

[Kdecherf]

First thanks for your hard work, I'm currently reviewing all your opened PR :)

I have mixed feeling about Flex structure. On one hand I guess we could postpone it as long as it is optional, but on the other hand I think it could improve upcoming contributions to the project. I don't know if it is best to move to flex before upgrading to sf5/sf6 or the other way around though.

[yguedidi]

Thanks for all the reviews and approves! :)

My personal vision about Flex is that brings 2 main benefits:

• a standard project structure
• a tool to easily add and upgrade third party dependencies

Based on that, it's really awesome when starting a new project as following standards from the beginning is good and you have no dependency yet so having a way to add them and have them configured directly is magic!
But for a project that already exist, with an already established structure, with already installed and configured dependencies, the Flex benefits have less impact..
At work I would love to move Flex, but it's always postponed because not needed, the project just works and developers know the structure, and we don't add new dependencies every day.

That being said, help having more upcoming contributions to the project is good, and so following the standard structure can help there!
It's the path I choose at work: slowly moving toward the standard structure, without the tooling.
Like moving templates and translations to their dedicated root directory, merging one by one bundles in the main one, etc

Let's see the point of view of @j0k3r as he already did a huge work on moving to Flex

[yguedidi]

I would anyway favor moving fast on Symfony upgrades first, especially that Symfony 5 upgrade is near the end, because Symfony upgrades will improve maintainability and security and open new possibilities.
By opposition to that the Flex upgrade looks less important as more about DX (even if DX is an important topic tho!)

[yguedidi]

For context, #6817 (comment), about in which version a PR fits:

As shared, I believe stale and waiting PRs are not good, there should always be a target branch for merging a PR.
Currently the only active branch is master, that corresponds to 2.6 AFAICT.
In a situation with 2 or 3 active branches (bugfix only branch, active/new features only branch, and optionally a next work branch), I would have said that all my recent PRs about depreciation removal, that are neither about bugfix neither about an end user new feature, would have better fit in the active/new feature branch if no next branch, or the next branch.

[yguedidi]

@nicosomb @Kdecherf @j0k3r congrats for the 2.6.3 release! 🎉
What about creating a 2.6 maintenance branch (or 2.6.x to be consistent with the existing 2.5.x) starting from the 2.6.3 commit?
So that all PRs for 2.7 can be merged in master, and so that we have a branch in which merge any needed future hotfix for 2.6

[nicosomb]

I agree with your proposal.

[nicosomb]

I just created 2.6.x branch: https://github.com/wallabag/wallabag/tree/2.6.x

[yguedidi]

@j0k3r what is your opinion about Flex, based on what I said above and regarding the big work you did?

[yguedidi]

I really believe it's possible to slowly but safely move to Flex structure first by small reviewable steps, I kind of started already using some recipes code in #6850

[j0k3r]

I agree with you about the complexity of keeping 3.0 & 2.x bugfix once the Flex change is merged.
I also think that if we don't do it for 3.0.0 (as it's kind of breaking change because of the file structure), we will never do it (or maybe on 4.0.0 but it won't happen until many years).

So I'm rather mixed feeling.
Maybe we can start moving slowly like you said and hope that once these slow steps will be done, the Flex move will be easier (and more reviewable) to do for 3.0.0.

[yguedidi]

as it's kind of breaking change because of the file structure

I'm wondering why file structure change is a breaking change. wallabag being a project installed by users, if I remember correctly the BC policy is on the API only, am I wrong here?

Maybe we can start moving slowly like you said and hope that once these slow steps will be done, the Flex move will be easier (and more reviewable) to do for 3.0.0.

Good! now that I know you're OK with this, I'll do some pull request about this from time to time, and yes, targeting to be released for 3.0 ;)

[j0k3r]

if I remember correctly the BC policy is on the API only, am I wrong here?

Well, because of permissions on folder, or other stuff people should have done in it. That's why we decided it will be a BC:

But the more we are working on that technical upgrade the more we think it will be a complex upgrade for people running a wallabag instance mostly because of the directory structure change.

[yguedidi]

Thanks! I better understand now