Release Engineering Team Change Request Requirements
If something is not clear...
If you are not sure about something during the code freeze, please ask. This Committers Guide entry outlines the typical order in which you should try to find the answer to your question.
If you are still unable to find an answer, please ask. re@ would prefer to receive "one more email" if it would clear up any confusion. Otherwise, we have no way to know that something is not clear.
If a question is asked enough times, we will document it.
Introduction
In the past, FreeBSD would have Code Freezes of the stable and sometimes even main branch during the period leading up to releases. This no longer happens. As of 2025, only the releng/X.Y branches get frozen.
The process for requesting changes depends on whether FreeBSD X.Y-RELEASE has happened yet. After the release, it is possible to fix security issues and critical bugs; this process results in Security Advisories and Errata Notices and is managed by secteam@.
For the rest of this document we will assume that the release has not yet happened.
If you are not a FreeBSD committer
If you find an issue with a pre-release version of FreeBSD, please work with a committer who is a subject matter expert in the affected area to deliver your patch following the standard development workflow. Please do not simply email your patch to re@.
Release cycle schedule
Minor releases follow a predictable schedule:
- The two weeks prior to BETA1 are designated as "code slush".
- Code slushes are purely advisory and not enforced by policy, but we recommend getting patches into the stable branch by the end of this period.
- On the first Friday of the second month of the quarter (e.g. February 6, 2026) the releng/X.Y branch is created and X.Y-BETA1 builds start.
- On the second, third, and fourth Fridays of the second month of the quarter, BETA2, BETA3, and RC1 builds start.
- If all goes as planned the X.Y-RELEASE builds start a week after that (the 5th Friday of the month or the 1st Friday of the third month of the quarter).
- The release is announced on the Tuesday after the release build starts.
With each BETA the guidelines for patches being accepted get tighter:
- Before BETA1, the releng/X.Y branch does not yet exist; commits can go into stable/X per normal. During the "code slush" it is recommended that commits with a potentially large "blast radius" (e.g. compiler/toolchain) be avoided though.
- Between BETA1 and BETA2, patches will usually be accepted which are not particularly large or dangerous.
- Between BETA2 and BETA3, patches will only be accepted given a high degree of confidence that they will not introduce any new problems.
- Note that "will not introduce any new problems" is not the same thing as "will correctly fix the problem identified". Sometimes bugs mask other, more serious bugs.
Between BETA3 and RC1, patches will only be accepted given a high degree of confidence that they will not introduce any new problems and confirmation that the problem being fixed is one which users are encountering in practice.
- At this point in the release cycle it isn't worth the risk of fixing a problem which is purely theoretical. Even "obviously correct" patches reviewed by several people sometimes turn out to not in fact be correct.
- Between RC1 and RELEASE, we aim to not accept any patches; exceptions are made for security fixes and occasionally for updates to man pages, but any larger changes will require adding another Release Candidate and delaying the Release, which we will only do if absolutely necessary.
The schedule for major (.0) releases is completely different from this, and will probably vary from major version to major version. Consult the FreeBSD website and email sent to the internal developers@ mailing list.
Change Request Process
Until FreeBSD 14.3, the release engineering team approved individual committers merging changes to release branches. This is no longer the process. Under normal circumstances the release engineer will be the only person pushing changes to the release branch.
If you have a change you want to get into the upcoming release:
- Send an email to re@ advising the team about the upcoming change.
- Please do not skip this step! It's important for the release engineering team to know about pending issues.
- Optionally, add the change to the tracking page on the wiki (Releng/X.YISSUES for appropriate X and Y).
- Land the change in the stable/X per the normal process (e.g. committing to main and merging 3+ days later).
- Send an email to re@ asking for the change to be cherry-picked for the release.
This email should contain:
The hash(es) of commit(s) in the stable branch which should be cherry-picked. If you are asking for multiple commits to be cherry-picked, please provide the hashes in a format which can be easily copied and pasted into a git cherry-pick command line (in particular, a list of raw hashes is more convenient than git log --pretty=oneline).
- An explanation of what problem is being fixed and testing / reviews / etc. which have been performed. Note that the amount needed here will depend on how close the release is (see "Release Cycle Schedule" above).
- Please provide this explanation even if you have been in recent communication with the release engineer about the issue; it might be the only thing you've been thinking about all day, but the release engineer might be context-switching between a dozen conversations about different issues.
Including the patch is not necessary (we know how to run git show) but may be helpful as part of the required explanation (e.g. if it's a one-line obviously-correct typo fix).
Cherry-pick request emails should go to re@ and not to the personal email address of the release engineer.