ChangeRequestGuidelines [FreeBSD WIKI]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Release Engineering Team Change Request Requirements ======

===== If something is not clear... =====

If you are not sure about something during the code freeze, please ask.
[[http://www.freebsd.org/doc/en/articles/committers-guide/if-in-doubt.html|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 [[https://docs.freebsd.org/en/articles/committers-guide/#git-primer|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 an svn merge 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@FreeBSD.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:

<code>
# git fetch freebsd
# git checkout releng/13.0
# git merge --ff-only freebsd/releng/13.0
# git cherry-pick -x <hash>
</code>

Once the change has been tested and the commit log updated (if necessary):

<code>
# git format-patch -1 --to=re@FreeBSD.org
</code>

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:

<code>
# git send-email -1 --to=re@FreeBSD.org
</code>

Once the request has been approved, rebase your local commit if needed and then push:

<code>
# git fetch freebsd
# git rebase freebsd/releng/13.0
# git push freebsd
</code>

=== 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:

<code>
# 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>
</code>

Once the changes have been tested and the commit logs updated (if necessary):

<code>
# git format-patch --to=re@FreeBSD.org freebsd/releng/13.0
</code>

or

<code>
# git send-email --compose --to=re@FreeBSD.org freebsd/releng/13.0
</code>

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 [[https://docs.freebsd.org/en/articles/freebsd-releng/#releng-wrapup-en|Release Engineering article]] for how and to whom to submit the request after the release cycle has completed.

----

{{tag>HowTo}}