4.0 | Rename master branch to stable

[jrfnl]

... and add a develop branch as the default WIP branch. The stable branch will become the release-only branch.

[greg0ire]

About the renaming, I think it's a good idea, about the default branch… I'm not sure. In doctrine/orm, we had a situation where master was once the default branch. Many, many contributors wrongly contributed backward-compatible changes to master, without being caught by maintainers. At some point I decided to switch to numbered branches, and backport PRs to either the next major or next minor branches. Many changes ended up in the next minor release. So I'd recommend to use stable as the default branch. It's the one that best reflects what people reporting issues against the software know anyway.

[jrfnl]

@greg0ire Thanks for your input. I'm going to have to have a think about that.

Many, many contributors wrongly contributed backward-compatible changes to master, without being caught by maintainers.

If I understand you correctly, you mean that master was used for the next major ?

My intention is to use develop as the running branch for PRs, with it being set to the default branch in GH. Releases would then merge develop into stable, whether it is for the next patch, minor or major.

The one thing I really don't want is to have long running "next major" branches, as is currently the case with the four year running 4.0 branch.... Also see the horrible task ahead of me described in #120...

[greg0ire]

If I understand you correctly, you mean that master was used for the next major ?

Yes exactly

I misunderstood what develop was, thanks for clarifying. It's not a workflow I'm familiar with, but if stable is not supposed to receive PRs at all, then I suppose it makes sense to have develop be the default.

The one thing I really don't want is to have long running "next major" branches, as is currently the case with the four year running 4.0 branch...

Ok so, if I understand correctly, this workflow is going to lead in a situation more similar to what firefox does, where there are major releases very often?

Also see the horrible task ahead of me described in #120...

That looks a lot with what I had to do with all the backports from 3 to 2. I feel your pain.

[asispts]

My intention is to use develop as the running branch for PRs, with it being set to the default branch in GH. Releases would then merge develop into stable, whether it is for the next patch, minor or major.

I'd like to know how you handle bug fixes, new features, and BC breaks in PRs using a single branch. In cases where the develop branch contains BC-breaking code, do you have to delay the release of a new patch/minor version until the next major release?

[jrfnl]

It's not a workflow I'm familiar with, but if stable is not supposed to receive PRs at all, then I suppose it makes sense to have develop be the default.

@greg0ire It's akin to a git-flow workflow, but not as strict ;-)

this workflow is going to lead in a situation more similar to what firefox does, where there are major releases very often?

Well, hopefully not with that much version inflation, but yes, I do intend to allow for more regular majors when the situation calls for it.
It'll hopefully be closer to what PHPUnit does, with a new major every year or so.

I have a rough outline of a roadmap/plan for 4.0 -> 5.0 -> 6.0 already, but the first focus in that regards is getting 4.0 in a releasable state, so I don't want to share too many ideas for the future at this time for fear of overpromising.

I'd like to know how you handle bug fixes, new features, and BC breaks in PRs using a single branch. In cases where the develop branch contains BC-breaking code, do you have to delay the release of a new patch/minor version until the next major release?

@asispts Well, delays like that may sometimes happen, but I would mostly try to avoid them by planning out merges carefully, similar to what has been done in this repo in the past.

If you look at the open PR list now, there are some things milestoned for 3.x Next (next patch release), some for 3.9.0 (next minor), some for 4.0.0 and I'll merge PRs - including my own - when the time is right for them, so 3.x Next PRs which are ready can be merged straight away, but I'll wait a little with merging 3.9.0 PRs until I'm sure the next release will be 3.9.0.

When getting close to the next major, I would create a 3.x branch for the final patch/minor releases of the old major and then let develop become the "next major". Obviously, that's talking about the future as I currently will first have to deal with the legacy of the past (the long-running 4.0 branch).

And yes, even though I could push straight to the develop (currently master) branch, I don't. I use PRs also for my own work.
There are a few reasons for that:

1. For maintenance PRs I use it as a QA check with the CI builds, which are faster than running all those checks locally. Those type of PRs will generally get merged quickly though.
2. For functional PRs, I want to give the community/interested parties a chance to review and voice opinions on what I've done (if they want to). I'd rather bugs get caught before merge than after and that includes the bugs I may accidentally create ;-)
   That's also the reason why I leave my own functional PRs open for a few days before merging them.
3. What with this being such a widely used package, I value the transparancy of PRs as always working via PRs allows for everyone who wants to (and watches the repo) to see what's going on.
4. With everything going via PRs, milestones will have the complete information about a release.
5. PRs and the potential discussions in them are good reference material to link to.

Does that help clarify things a bit more ?

[greg0ire]

For me it does 🙂

If I understand correctly, you're "storing" improvements in the next minor milestone, and breaking changes in the next major milestone, and then when the time comes, you merge all at once, probably not with an octopus merge though 😅

I guess you don't wait for too long though because otherwise the merge/rebases must be quite painful. It sounds like a lot of work to be honest, but I suppose it all depends on the actual number of PRs in a milestone, and from what I saw in 3.9.0 there aren't that many (and since you're the author of many of them, and the PRs are recent, it's probably not that hard).

100% agree on using PRs for absolutely every change 👍

[jrfnl]

@greg0ire Correct and yes, I don't intend to let things wait for too long. I also have a GH Actions workflow already set up which automatically labels PRs with merge conflicts, so it's pretty straight forward to see what needs a rebase and if there is one thing I've become good at over the years, it's rebases, so I'm not concerned about the current merge flow and will be happy to revisit if it would become a problem.

[jrfnl]

@greg0ire Just read up on octopus merges, hadn't come across that term before.

And no, when I do those kind of "merge sprees", I will merge one PR at a time and for all my own PRs, rebase before merging the next one, to make sure that if there is a CI failure due to one change having an unexpected impact elsewhere, it can be easily identified and gets caught before the merge.

That's also how I merged my own PRs which had been waiting to be merged in the squizlabs repo (for ages) and which I'd ported over and included in the 3.8.0 release.

[greg0ire]

@greg0ire Just read up on octopus merges, hadn't come across that term before.

I've done them once in my life, at work, for a merge release train, in a case when I was somehow sure in advance there wouldn't be any conflicts. It was fun but I wouldn't recommend it 🤣 The way you're describing is safer indeed 👍