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 order to submit a patch to the Release Engineering Team for a branch during Code Freeze you must be a FreeBSD Developer with proper commit privileges to commit the patch. If you are not a committer you need to contact a committer and have them submit the request. You only need to send a request when committing to a branch that is in code freeze. For most releases it will be a stable branch that gets frozen first (for example stable/13). But as the release process progresses the release branch (for example releng/13.0) will be created. After the release branch is created it will be frozen and the Release Engineering Team will release the code freeze on the stable branch. So for most cases you will need to submit requests for you will be requesting a merge, not a direct commit and that is what is described in the first section below. Only during the first part of the release process for a brand new stable branch (an X.0 release) would head be frozen. That situation is described in the second section below.
Note to committers that normally require approval for commits:
Before sending the approval request to re@, the commit should already have the approval that would normally be required. This means that before sending the change to re@, approval must have already been granted by mentor(s)/maintainer(s)/etc. When re@ receives the approval request, the change should be ready to commit immediately upon receiving re@ approval. Please indicate in your request for commit approval that the change has been approved by the mentor(s)/maintainer(s)/etc.
It is also recommended to CC the approver(s) of the change when sending the request for approval to re@.
Also please be sure to include the proposed commit message with the change request.
Change Request Requirements
IMPORTANT: Code reviews marked as 'Accepted' in Phabricator, regardless of if the reviewer of the change is a member of re@, are not implicit approval for the change to be committed to the tree. The guidelines outlined here must be adhered to, and any commit violating this policy will be reverted without further question.
Please follow these requirements when submitting patches for anything other than main. All submissions must:
Include complete patches inline or attached to the e-mail generated as described below. Just forwarding the MFC reminder email message or sending a URL to the changeset description of the original commit on https://cgit.freebsd.org/ is not sufficient.
The diff(s) should be generated from commit(s) merged to a local branch of the destination branch as described in the Committers Guide. Commit logs should be ready for commit including metadata such as reviewers.
- The change should be fully build- and run-time tested.
- If the change is something that would normally, by standard FreeBSD Project practice, require review mention the information about who has reviewed the change.
- If not sending the request from your FreeBSD email address, mention your login in the email.
- Indicate the branch(es) you intend to merge to.
- If a commit is a direct commit instead of a merge, indicate this in the commit log and include the reason in the commit log.
Unless exceptional circumstances apply, the change should have been in main for at least three days before a merge is requested (which is standard FreeBSD Project policy). If a MFC timeout had been specified in the original commit you should wait for that time to expire before sending in the commit request. Please do not send in the commit request before the MFC time expires. The entire point of the MFC timeout period is to give some time for other developers to comment on the change and/or have it get a little testing. So until the MFC time expires you are not actually sure you should do the MFC. The only time you should send in the request early is if, prompted by mail from the RE Team saying that a "release event" is coming up (for example a BETA or RC build), you want to make sure your change is included in that "event". Sometimes it's better to MFC something a little early so it is included in a BETA or RC build.
As mentioned in the Introduction, during the late stages of the release process the Release Engineering Team creates the releng branch (for example releng/13.0) and unfreezes the corresponding stable branch (for example stable/13). When the release process is at that stage you can do the merge to the stable branch without requesting approval first, and at that point prepare a request to merge the change from the stable branch to the releng branch (for example the request should be a git cherry-pick from stable/13 to releng/13.0).
Please follow these requirements when it is main that is in code freeze (the start of a X.0 release):
- Include complete patches inline or attached to the e-mail generated as described below.
The diff(s) should be generated from commit(s) on a local branch of main. Commit logs should be ready for commit including metadata such as reviewers.
- The change should be fully build- and run-time tested.
- If the change is something that would normally, by standard FreeBSD Project practice, require review mention the information about who has reviewed the change. The Release Engineering Team will be deciding if your request is "too risky" to be part of the release given the current state of the release process. We are NOT a substitute for normal FreeBSD Project maintainer, peer, or community review practices.
- If not sending the request from your FreeBSD email address, mention your login in the email.
Requests that do not follow these requirements may be rejected without further consideration.
Submitting a Request via `git format-patch` or `git send-email`
Patches generated via git format-patch should be sent directly to <re AT FreeBSD DOT org> via the --to option. Additional individuals can be cc'd via via --cc. Note that git may automatically cc additional folks (for example, when submitting a request for a commit authored by a different person than the committer).
Single Commit Example
Merging the change:
# git fetch freebsd # git checkout releng/13.0 # git merge --ff-only freebsd/releng/13.0 # git cherry-pick -x <hash>
Once the change has been tested and the commit log updated (if necessary):
# git format-patch -1 --to=re@FreeBSD.org
This will generate a file named 0001-<first line of commit log>.patch containing an e-mail message. You can send this e-mail using a MUA. If you have git send-email configured, you can use git send-email to send the e-mail directly instead:
# git send-email -1 --to=re@FreeBSD.org
Once the request has been approved, rebase your local commit if needed and then push:
# git fetch freebsd # git rebase freebsd/releng/13.0 # git push freebsd
Multiple Commit Example
To request approval for a merge of a series of commits, merge the series locally and then send a mail for each commit:
Merging the changes:
# git fetch freebsd # git checkout releng/13.0 # git merge --ff-only freebsd/releng/13.0 # git cherry-pick -x <first hash> # git cherry-pick -x <second hash> ... # git cherry-pick -x <last hash>
Once the changes have been tested and the commit logs updated (if necessary):
# git format-patch --to=re@FreeBSD.org freebsd/releng/13.0
or
# git send-email --compose --to=re@FreeBSD.org freebsd/releng/13.0
The --compose option to git send-email will open up your EDITOR to write a cover letter. Please include context for the patch(es) in the cover letter; at a minimum, which branch you are seeking approval to merge it to.
Submitting a Request via `git show`
If you are not using git format-patch or git send-email, then generate a diff for each commit via git show -p --raw and provide the output to re@ as an attachment or in-line email.
Submitting a Request for an Errata Notice
If a member of Release Engineering informs you that a request for commit approval is not approved but will be considered as a post-release Errata Notice, see the Release Engineering article for how and to whom to submit the request after the release cycle has completed.