Document branch cutting in release management #1548

Ryuno-Ki commented 2025年10月17日 12:13:57 +02:00

In forgejo/forgejo#6931 (comment) we learned that there is a feature freeze period (around three weeks before a release) that might prevent PRs from getting merged into a release.

The dates were lost during forgejo/docs@291747bcfb

Is there something preventing us to bring them back? It could avoid frustrations from contributors (again, see the referenced PR).

In https://codeberg.org/forgejo/forgejo/pulls/6931#issuecomment-7771481 we learned that there is a feature freeze period (around three weeks before a release) that might prevent PRs from getting merged into a release. The dates were lost during https://codeberg.org/forgejo/docs/commit/291747bcfb8fc6453af33766f7acb46be13d9f03 Is there something preventing us to bring them back? It could avoid frustrations from contributors (again, see the referenced PR).

Beowulf commented 2025年10月17日 13:49:49 +02:00

Feature freeze is when the branch is cut: https://forgejo.org/docs/latest/admin/release-schedule/

Feature freeze is when the branch is cut: https://forgejo.org/docs/latest/admin/release-schedule/

Beowulf commented 2025年10月17日 13:51:02 +02:00

Because then PRs need to be backported and backports only happens for bug fixes.

Because then PRs need to be backported and backports only happens for bug fixes.

earl-warren commented 2025年10月17日 14:47:07 +02:00

There is no feature freeze. Around the dates branch is cut, features can still be merged and backported. The members of the merger team evaluate the risk of doing so since merging a new feature close to the release date is increasingly risky as time passes. Although cutting the branch usually happens three weeks before the release but it is not a set requirement not should it be: there is no benefit in doing that and flexibility helps members of the release team organize their schedule.

The pull request you refer to should have been in v13.0.0 but it was forgotten by everyone it seems, including me. This is an accident independent of when the branch is cut.

There is no feature freeze. Around the dates branch is cut, features can still be merged and backported. The members of the merger team evaluate the risk of doing so since merging a new feature close to the release date is increasingly risky as time passes. Although cutting the branch usually happens three weeks before the release but it is not a set requirement not should it be: there is no benefit in doing that and flexibility helps members of the release team organize their schedule. The pull request you refer to should have been in v13.0.0 but it was forgotten by everyone it seems, including me. This is an accident independent of when the branch is cut.

sclu1034 commented 2025年10月17日 14:57:02 +02:00

The fact that several people regularly involved with the project all had different information about this suggests that there definitely should be something added to the docs. The release schedule indicates that branches are being cut, but neither it, nor Release Management explain it.

@earl-warren wrote in #1548 (comment):

cutting the branch usually happens three weeks before the release but it is not a set requirement not should it be

The fixed date in the release schedule would be contrary to that, so it should probably be removed then.

The fact that several people regularly involved with the project all had different information about this suggests that there definitely should be _something_ added to the docs. The release schedule indicates that branches are being cut, but neither it, nor [Release Management](https://forgejo.org/docs/latest/contributor/release/) explain it. @earl-warren wrote in https://codeberg.org/forgejo/docs/issues/1548#issuecomment-7773485: > cutting the branch usually happens three weeks before the release but it is not a set requirement not should it be The fixed date in the release schedule would be contrary to that, so it should probably be removed then.

mfenniak commented 2025年10月17日 15:08:43 +02:00

We could document guidelines around backporting into a release branch, to help clarify. This was discussed in Matrix recently and @0ko wrote out this outline for determining whether to backport:

• it is a feature or changes database
  • cannot backport to stable release (i.e. for v13.0.1 after v13.0.0 is out)
  • technically cannot backport to prerelease after branch cut because feature freeze, but if you really want then maybe you can (i.e. for v13.0.0 right now)
• it is a fix to a regression introduced in this major version, before the release
  • really need to backport, doesn't matter how
• it is a fix to a regression of this major version after the release
  • kind of need to backport but depends on the regression, mostly yes
• it is a fix for some old bug
  • depends on: fix blast radius, how good testing is, how many users are affected. some can be backported, some can wait until next major version

This is excerpted directly from Matrix, off the cuff, and would need a round of refinement. In particular I think the phrase "feature freeze" reintroduces complexity, where the intent is probably better described as "after the release branch is cut, it's a time for stabilization and testing; the volume and size of changes should be judged cautiously to match this goal".

We could document guidelines around backporting into a release branch, to help clarify. This was discussed in Matrix recently and @0ko wrote out this outline for determining whether to backport: - it is a feature or changes database - cannot backport to stable release (i.e. for v13.0.1 after v13.0.0 is out) - technically cannot backport to prerelease after branch cut because feature freeze, but if you really want then maybe you can (i.e. for v13.0.0 right now) - it is a fix to a regression introduced in this major version, before the release - really need to backport, doesn't matter how - it is a fix to a regression of this major version after the release - kind of need to backport but depends on the regression, mostly yes - it is a fix for some old bug - depends on: fix blast radius, how good testing is, how many users are affected. some can be backported, some can wait until next major version This is excerpted directly from Matrix, off the cuff, and would need a round of refinement. In particular I think the phrase "feature freeze" reintroduces complexity, where the intent is probably better described as "after the release branch is cut, it's a time for stabilization and testing; the volume and size of changes should be judged cautiously to match this goal".

earl-warren commented 2025年10月17日 15:25:50 +02:00

I respectfully think this is an attempt to fix a non existent problem. Yes, every member of the mergers and release team has a different view on the matter. The effort to create a process, rules and the friction of enforcing them would be very counter productive.

I think it is fine if each member of the release / mergers team share their own thought process in the way @mfenniak just did and maybe add them to the documentation for information. Creating rules combining their respective views into a handbook that needs to be obeyed is quite different.

I respectfully think this is an attempt to fix a non existent problem. Yes, every member of the mergers and release team has a different view on the matter. The effort to create a process, rules and the friction of enforcing them would be very counter productive. I think it is fine if each member of the release / mergers team share their own thought process in the way @mfenniak just did and maybe add them to the documentation for information. Creating rules combining their respective views into a handbook that needs to be obeyed is quite different.

mfenniak commented 2025年10月17日 15:49:47 +02:00

I think that's fair. So the PR in question was marked for auto-merge and nothing happened -- do we have an open issue for that problem? Fixing a technical problem is easy (relatively). 🙂

I think that's fair. So the PR in question was marked for auto-merge and nothing happened -- do we have an open issue for that problem? Fixing a technical problem is easy (relatively). 🙂

earl-warren commented 2025年10月17日 15:50:10 +02:00

@sclu1034 wrote in #1548 (comment):

@earl-warren wrote in #1548 (comment):

cutting the branch usually happens three weeks before the release but it is not a set requirement not should it be

The fixed date in the release schedule would be contrary to that, so it should probably be removed then.

It is needed and was added so people are not surprised. That happened before it was added. There needs to be clarity that in theory it will happen at that date.

Now the practical impact of this branch cut happening a few days before or a few days later is non existent. The worst that can happen is that a few more pull request will need to be backported. Literally nothing else.

Does it happen 24h before a feature is merged? It is not a problem, if the merger thinks the feature is solid and ready, they can backport it. There is no hard consequence of "missing the cut date" and there never was.

@sclu1034 wrote in https://codeberg.org/forgejo/docs/issues/1548#issuecomment-7774109: > @earl-warren wrote in #1548 (comment): > > > cutting the branch usually happens three weeks before the release but it is not a set requirement not should it be > > The fixed date in the release schedule would be contrary to that, so it should probably be removed then. It is needed and was added so people are not surprised. That happened before it was added. There needs to be clarity that in theory it will happen at that date. Now the practical impact of this branch cut happening a few days before or a few days later is non existent. The worst that can happen is that a few more pull request will need to be backported. Literally nothing else. Does it happen 24h before a feature is merged? It is not a problem, if the merger thinks the feature is solid and ready, they can backport it. There is no hard consequence of "missing the cut date" and there never was.

earl-warren commented 2025年10月17日 17:42:31 +02:00

@mfenniak wrote in #1548 (comment):

I think that's fair. So the PR in question was marked for auto-merge and nothing happened -- do we have an open issue for that problem? Fixing a technical problem is easy (relatively). 🙂

This is an extremely elusive problem for which there is no reproducer at this time. I don't recall seeing it happen anywhere but on Codeberg but maybe I mental blocked it. There was a fix for one cause that made it rather frequent but it was evidently not all of it (I don't recall the pull request but I can dig it up if you don't find it).

@mfenniak wrote in https://codeberg.org/forgejo/docs/issues/1548#issuecomment-7774661: > I think that's fair. So the PR in question was marked for auto-merge and nothing happened -- do we have an open issue for that problem? Fixing a technical problem is easy (relatively). :slightly_smiling_face: This is an extremely elusive problem for which there is no reproducer at this time. I don't recall seeing it happen anywhere but on Codeberg but maybe I mental blocked it. There was a fix for one cause that made it rather frequent but it was evidently not all of it (I don't recall the pull request but I can dig it up if you don't find it).