Feature branch: 5.0 public api breakage

[fwh-dc]

In order to support ongoing development on the public api in between two major releases I propose to create a feature branch were work that will break the api can be merged.

As 4.0 approached there was rush of PR’s created that required approvals before the deadline.
This feature branch allows us to avoid the rush and cleanup the api in an “organic” manner.

In order to minimize maintenance of rebasing the branch until 5.0 I want to define a policy.

Forexample:
If an api function is used internally, then the function cannot be removed entirely but it must instead be moved to an internal header.

There may be other worries, please put them forward.

[nhorman]

I'm not opposed to such a policy, but, just to ask the question, isn't the feature branch usable for this purpose? i.e. if you want to create a feature that breaks abi, just request a feature branch, and note that it cannot be merged until such time as the next major release is being tracked on master?

[fwh-dc]

That's what I am trying to do here 😁 I tried to follow the process described here: https://openssl-library.org/policies/general/feature-branch-approval-policy/ by creating a feature issue in this repo.

Please let me know the right way to propose a feature branch creation if this is not it :)

[nhorman]

Ah, I see, you want a generic/catchall feature branch for anything that breaks ABI between now and 5.0. That makes more sense.

That said, and I'm speaking only for myself here, Id have to think about the implications here somewhat. What we would be looking at is effectively a "next-major" branch, that just kind of hangs out in parallel with the master branch, waiting for main to start tracking the next major release at which point it could be merged with master.

Features with ABI breaking changes would be merged to the next-major branch, instead of master, so that the work could be considered "complete" from the standpoint of the developer, and just pending merge for the above prerequisites. Do I have your idea correct?

Assuming I do, that would be beneficial, in that it would let people work on ABI breaking changes anytime without having to push for reviews/rush to merge during the 6 month development window between the last minor X.Y and the subsequent major X+1.0. It would also create a future view of what the next major is expected to look like for any interested parties. That would be nice.

The difficulty that I would see with such an effort would be that it creates significant workloads for the person maintaining that branch. I.e. someone is going to have to rebase that branch regularly for the next N years, N being the number of years between major releases (currently 5 years, but hopefully less between 4.0 and 5.0). If such a "next" branch becomes large, thats potentially alot of work for whatever poor soul(s) get assigned that duty.

I suppose the alternate solution is to do what we do now - i.e. create a topic-specific feature branch (in your case something to hold the ABI-breaking SSL_select_next_proto_changes you're proposing), and label the branch as having a hold until the next major is open for development. Doing so follows our current process and shards the workload among the developers undertaking the effort to create ABI breaking changes. Its still not a small amount of work to keep a feature branch up to date until the next major is ready, but at least its spread out among participating developers.

A 3rd solution might be a multi-level branching scheme. i.e. something like this:

master -----------------------------------------------------------------
                     |
                      ------------------ X.0.0----------X.0.1----------X.0.2
                                                                          |
                                                                           --------- X.1.0---------X.1.1----------X.1.2
                                                                                                                |
                                                                                                                --------X.2.0-------X.2.1--------X.2.2

That would let us declare that master always tracks the next major release, and would always be open for ABI breaking changes, while subsequent minor releases were always branched from their last parent minor.

That would be a significant undertaking for our tooling of course, So perhaps not feasible, at least in the short term

I don't know, What do you think @mattcaswell @t8m @t-j-h

[fwh-dc]

Features with ABI breaking changes would be merged to the next-major branch, instead of master, so that the work could be considered "complete" from the standpoint of the developer, and just pending merge for the above prerequisites. Do I have your idea correct?

Spot on.

The difficulty that I would see with such an effort would be that it creates significant workloads for the person maintaining that branch. I.e. someone is going to have to rebase that branch regularly for the next N years, N being the number of years between major releases (currently 5 years, but hopefully less between 4.0 and 5.0). If such a "next" branch becomes large, thats potentially alot of work for whatever poor soul(s) get assigned that duty.

I understand that it is no free lunch, but there are many examples like the SSL_select_next_proto() changes that needs to wait, and gets forgotten when we get near the major release date. Especially in the case that is not a long term contributor, we end up with PR's that are just stuck eventhough they are valueable to the project.

So that why I am proposing that a policy is defined for the feature branch for which the goal is to define some criteria for acceptable contribution that lessen the burden on the "poor rebase guy".

I suppose the alternate solution is to do what we do now - i.e. create a topic-specific feature branch (in your case something to hold the ABI-breaking SSL_select_next_proto_changes you're proposing)

I would expect that the less branches the merrier, but I don't know..

[fwh-dc]

Here's another example of what I would say would require low effort in maintaining on a seperate feature branch: openssl/openssl#30572

Perhabs we could specify feature branches for specific topics: const correctness, boolean in public functions, api-removal, etc.

Have you spent time considering this approach? @nhorman @t8m @mattcaswell @t-j-h.

[nhorman]

@fwh-dc specifying feature branches for specific topics is pretty much what we do now (i.e. we currently/recently had feature branches for quic 0-rtt/hqc/X509 constification/etc). the issue you cite above was just missed during that effort.

speaking only for myself, I like the idea of a next-major branch in principle, in that it creates a single point to merge changes that for whatever reason can't be merged immediately (primarily I would think for ABI compat reasons). A single target branch also makes it easier to know where such changes should go (i.e. feature branches with a large enough topic results in developers not really knowing where some work should be targeted). My only concern is (as noted above), is that it places a potentially significant work effort on a developer maintaining that branch for a long period of time.