Committer's Guide

1. Install security/gnupg. Enter these lines in ~/.gnupg/gpg.conf to set minimum acceptable defaults for signing and new key preferences (see the GnuPG options documentation for more details):

   # Sorted list of preferred algorithms for signing (strongest to weakest).
   personal-digest-preferences SHA512 SHA384 SHA256 SHA224
   # Default preferences for new keys
   default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 CAMELLIA256 AES192 CAMELLIA192 AES CAMELLIA128 CAST5 BZIP2 ZLIB ZIP Uncompressed

2. Generate a key:

   % gpg --full-gen-key
   gpg (GnuPG) 2.1.8; Copyright (C) 2015 Free Software Foundation, Inc.
   This is free software: you are free to change and redistribute it.
   There is NO WARRANTY, to the extent permitted by law.
   Warning: using insecure memory!
   Please select what kind of key you want:
      (1) RSA and RSA (default)
      (2) DSA and Elgamal
      (3) DSA (sign only)
      (4) RSA (sign only)
   Your selection? 1
   RSA keys may be between 1024 and 4096 bits long.
   What keysize do you want? (2048) 2048 (1)
   Requested keysize is 2048 bits
   Please specify how long the key should be valid.
   	 0 = key does not expire
         <n>  = key expires in n days
         <n>w = key expires in n weeks
         <n>m = key expires in n months
         <n>y = key expires in n years
   Key is valid for? (0) 3y (2)
   Key expires at Wed Nov  4 17:20:20 2015 MST
   Is this correct? (y/N) y
   GnuPG needs to construct a user ID to identify your key.
   Real name: Chucky Daemon (3)
   Email address: notreal@example.com
   Comment:
   You selected this USER-ID:
   "Chucky Daemon <notreal@example.com>"
   Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o
   You need a Passphrase to protect your secret key.

• All committers may modify src/share/misc/committers-*.dot, src/usr.bin/calendar/calendars/calendar.freebsd, and ports/astro/xearth/files.

• doc committers may commit documentation changes to src files, such as manual pages, READMEs, fortune databases, calendar files, and comment fixes without approval from a src committer, subject to the normal care and tending of commits.

• Any committer may make changes to any other tree with an "Approved by" from a non-mentored committer with the appropriate bit. Mentored committers can provide a "Reviewed by" but not an "Approved by".

• Committers can acquire an additional bit by the usual process of finding a mentor who will propose them to core, doceng, or portmgr, as appropriate. When approved, they will be added to 'access' and the normal mentoring period will ensue, which will involve a continuing of "Approved by" for some period.

4.1.1. Documentation Implicit (Blanket) Approval

Some types of fixes have "blanket approval" from the Documentation Engineering Team <doceng@FreeBSD.org>, allowing any committer to fix those categories of problems on any part of the doc tree. These fixes do not need approval or review from a doc committer if the author doesn’t have a doc commit bit.

Blanket approval applies to these types of fixes:

Over the years, some implicit approvals were granted in the doc tree. This list shows the most common cases:

5.2.1. Scope

If you want to download FreeBSD, compile it from sources, and generally keep up to date that way, this primer is for you. It covers getting the sources, updating the sources, bisecting and touches briefly on how to cope with a few local changes. It covers the basics, and tries to give good pointers to more in-depth treatment for when the reader finds the basics insufficient. Other sections of this guide cover more advanced topics related to contributing to the project.

The goal of this section is to highlight those bits of Git needed to track sources. They assume a basic understanding of Git. There are many primers for Git on the web, but the Git Book provides one of the better treatments.

5.2.2. Getting Started For Developers

This section describes the read-write access for committers to push the commits from developers or contributors.

% git config --add remote.freebsd.fetch '+refs/internal/*:refs/internal/*'
% git fetch
% git checkout -b admin internal/admin

git worktree add -b admin ../${repo}-admin internal/admin

git push freebsd HEAD:refs/internal/admin

5.2.3. Keeping Current With The FreeBSD src Tree

First step: cloning a tree. This downloads the entire tree. There are two ways to download. Most people will want to do a deep clone of the repository. However, there are times when you may wish to do a shallow clone.

% git clone -o freebsd $URL -b branch [<directory>]

% git clone -o freebsd -b branch --depth 1 $URL [dir]

% cd src
% make buildworld
% make buildkernel
% make installkernel
% make installworld

5.2.4. Selecting a Specific Version

In Git, git checkout checks out both branches and specific versions. Git’s versions are the long hashes rather than a sequential number.

When you checkout a specific version, just specify the hash you want on the command line (the git log command can help you decide which hash you might want):

% git checkout 08b8197a74

and you have that checked out. You will be greeted with a message similar to the following:

Note: checking out '08b8197a742a96964d2924391bf9fdfeb788865d'.
You are in a 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by performing another checkout.
If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -b with the checkout command again. Example:
  git checkout -b <new-branch-name>
HEAD is now at 08b8197a742a hook gpiokeys.4 to the build

where the last line is generated from the hash you are checking out and the first line of the commit message from that revision. The hash can be abbreviated to the shortest unique length. Git itself is inconsistent about how many digits it displays.

5.2.5. Bisecting

Sometimes, things go wrong. The last version worked, but the one you just updated to does not. A developer may ask you to bisect the problem to track down which commit caused the regression.

Git makes bisecting changes easy with a powerful git bisect command. Here’s a brief outline of how to use it. For more information, you can view https://www.metaltoad.com/blog/beginners-guide-git-bisect-process-elimination or https://git-scm.com/docs/git-bisect for more details. The man git-bisect page is good at describing what can go wrong, what to do when versions won’t build, when you want to use terms other than 'good' and 'bad', etc, none of which will be covered here.

git bisect start --first-parent will start the bisection process. Next, you need to tell a range to go through. git bisect good XXXXXX will tell it the working version and git bisect bad XXXXX will tell it the bad version. The bad version will almost always be HEAD (a special tag for what you have checked out). The good version will be the last one you checked out. The --first-parent argument is necessary so that subsequent git bisect commands do not try to check out a vendor branch which lacks the full FreeBSD source tree.

5ef0bd68b515 (HEAD -> main, freebsd/main, freebsd/HEAD) HEAD@{0}: pull --ff-only: Fast-forward
a8163e165c5b (upstream/main) HEAD@{1}: checkout: moving from b6fb97efb682994f59b21fe4efb3fcfc0e5b9eeb to main
...

Set the 'good' version first, then set the bad (though the order doesn’t matter). When you set the bad version, it will give you some statistics on the process:

% git bisect start --first-parent
% git bisect good a8163e165c5b
% git bisect bad HEAD
Bisecting: 1722 revisions left to test after this (roughly 11 steps)
[c427b3158fd8225f6afc09e7e6f62326f9e4de7e] Fixup r361997 by balancing parens.  Duh.

You would then build/install that version. If it’s good you’d type git bisect good otherwise git bisect bad. If the version doesn’t compile, type git bisect skip. You will get a similar message to the above after each step. When you are done, report the bad version to the developer (or fix the bug yourself and send a patch). git bisect reset will end the process and return you back to where you started (usually tip of main). Again, the git-bisect manual (linked above) is a good resource for when things go wrong or for unusual cases.

5.2.6. Signing the commits, tags, and pushes, with GnuPG

Git knows how to sign commits, tags, and pushes. When you sign a Git commit or a tag, you can prove that the code you submitted came from you and wasn’t altered while you were transferring it. You also can prove that you submitted the code and not someone else.

A more in-depth documentation on signing commits and tags can be found in the Git Tools - Signing Your Work chapter of the Git’s book.

The best way is to simply tell Git you always want to sign commits, tags, and pushes. You can do this by setting a few configuration variables:

% git config --add user.signingKey LONG-KEY-ID
% git config --add commit.gpgSign true
% git config --add tag.gpgSign true
% git config --add push.gpgSign if-asked

5.2.7. Ports Considerations

The ports tree operates the same way. The branch names are different and the repositories are in different locations.

There is also a mirror on GitHub, see External mirrors for an overview. The latest branch is main. The quarterly branches are named yyyyQn for year 'yyyy' and quarter 'n'.

category/port: Summary.
Description of why the changes where made.
PR:	    12345

5.2.8. Managing Local Changes

This section addresses tracking local changes. If you have no local changes you can skip this section.

One item that is important for all of them: all changes are local until pushed. Unlike Subversion, Git uses a distributed model. For users, for most things, there is very little difference. However, if you have local changes, you can use the same tool to manage them as you use to pull in changes from FreeBSD. All changes that you have not pushed are local and can easily be modified (git rebase, discussed below does this).

% cd src
% git checkout main
% git checkout -b no-color-ls
% cd bin/ls
% vi ls.c     # hack the changes in
% git diff    # check the changes
diff --git a/bin/ls/ls.c b/bin/ls/ls.c
index 7378268867ef..cfc3f4342531 100644
--- a/bin/ls/ls.c
+++ b/bin/ls/ls.c
@@ -66,6 +66,7 @@ __FBSDID("$FreeBSD$");
 #include <stdlib.h>
 #include <string.h>
 #include <unistd.h>
+#undef COLORLS
 #ifdef COLORLS
 #include <termcap.h>
 #include <signal.h>
% # these look good, make the commit...
% git commit ls.c

% git checkout main
% git pull --ff-only
% git rebase -i main no-color-ls

Auto-merging bin/ls/ls.c
CONFLICT (content): Merge conflict in bin/ls/ls.c
error: could not apply 646e0f9cda11... no color ls
Resolve all conflicts manually, mark them as resolved with
"git add/rm <conflicted_files>", then run "git rebase --continue".
You can instead skip this commit: run "git rebase --skip".
To abort and get back to the state before "git rebase", run "git rebase --abort".
Could not apply 646e0f9cda11... no color ls

 <<<<<<< HEAD
 #ifdef COLORLS_NEW
 #include <terminfo.h>
 =======
 #undef COLORLS
 #ifdef COLORLS
 #include <termcap.h>
 >>>>>>> 646e0f9cda11... no color ls
....
The new code is first, and your code is second.
The right fix here is to just add a #undef COLORLS_NEW before #ifdef and then delete the old changes:
[source,shell]
....
#undef COLORLS_NEW
#ifdef COLORLS_NEW
#include <terminfo.h>
....
save the file.
The rebase was interrupted, so you have to complete it:
[source,shell]
....
% git add ls.c
% git rebase --continue
....

% git checkout main
% # build and install here...

% git checkout no-color-ls
% git checkout -b no-color-ls-stable-12   # create another name for this branch
% git rebase -i stable/12 no-color-ls --onto main

5.3.1. Summary

MFC workflow can be summarized as git cherry-pick -x plus git commit --amend to adjust the commit message. For multiple commits, use git rebase -i to squash them together and edit the commit message.

5.3.2. Single commit MFC

% git checkout stable/X
% git cherry-pick -x $HASH --edit

For MFC commits, for example a vendor import, you would need to specify one parent for cherry-pick purposes. Normally, that would be the "first parent" of the branch you are cherry-picking from, so:

% git checkout stable/X
% git cherry-pick -x $HASH -m 1 --edit

If things go wrong, you’ll either need to abort the cherry-pick with git cherry-pick --abort or fix it up and do a git cherry-pick --continue.

Once the cherry-pick is finished, push with git push. If you get an error due to losing the commit race, use git pull --rebase and try to push again.

5.3.3. MFC to RELENG branch

MFCs to branches that require approval require a bit more care. The process is the same for either a typical merge or an exceptional direct commit.

% git checkout releng/13.0
% git cherry-pick -x $HASH --edit

If you forget to to add the Approved by: line, you can do a git commit --amend to edit the commit message before you push the change.

5.3.4. Multiple commit MFC

% git checkout -b tmp-branch stable/X
% for h in $HASH_LIST; do git cherry-pick -x $h; done
% git rebase -i stable/X
# mark each of the commits after the first as 'squash'
# Update the commit message to reflect all elements of commit, if necessary.
# Be sure to retain the "cherry picked from" lines.
% git push freebsd HEAD:stable/X

If the push fails due to losing the commit race, rebase and try again:

% git checkout stable/X
% git pull
% git checkout tmp-branch
% git rebase stable/X
% git push freebsd HEAD:stable/X

Once the MFC is complete, you can delete the temporary branch:

% git checkout stable/X
% git branch -d tmp-branch

5.3.5. MFC a vendor import

Vendor imports are the only thing in the tree that creates a merge commit in the main branch. Cherry picking merge commits into stable/XX presents an additional difficulty because there are two parents for a merge commit. Generally, you’ll want the first parent’s diff since that’s the diff to main (though there may be some exceptions).

% git cherry-pick -x -m 1 $HASH

is typically what you want. This will tell cherry-pick to apply the correct diff.

There are some, hopefully, rare cases where it’s possible that the main branch was merged backwards by the conversion script. Should that be the case (and we’ve not found any yet), you’d change the above to -m 2 to pickup the proper parent. Just do:

% git cherry-pick --abort
% git cherry-pick -x -m 2 $HASH

to do that. The --abort will cleanup the failed first attempt.

5.3.6. Redoing a MFC

If you do a MFC, and it goes horribly wrong and you want to start over, then the easiest way is to use git reset --hard like so:

% git reset --hard freebsd/stable/12

though if you have some revs you want to keep, and others you don’t, using git rebase -i is better.

5.3.7. Considerations when MFCing

When committing source commits to stable and releng branches, we have the following goals:

With Subversion, we used the following practices to achieve these goals:

With Git, we will need to use different strategies to achieve the same goals. This document aims to define best practices when merging source commits using Git that achieve these goals. In general, we aim to use Git’s native support to achieve these goals rather than enforcing practices built on Subversion’s model.

One general note: due to technical differences with Git, we will not be using Git "merge commits" (created via git merge) in stable or releng branches. Instead, when this document refers to "merge commits", it means a commit originally made to main that is replicated or "landed" to a stable branch, or a commit from a stable branch that is replicated to a releng branch with some variation of git cherry-pick.

5.3.8. Finding Eligible Hashes to MFC

Git provides some built-in support for this via the git cherry and git log --cherry commands. These commands compare the raw diffs of commits (but not other metadata such as log messages) to determine if two commits are identical. This works well when each commit from main is landed as a single commit to a stable branch, but it falls over if multiple commits from main are squashed together as a single commit to a stable branch. The project makes extensive use of git cherry-pick -x with all lines preserved to work around these difficulties and is working on automated tooling to take advantage of this.

5.3.9. Commit message standards

5.4.1. Branch naming convention

All vendor branches and tags start with vendor/. These branches and tags are visible by default.

We will explore an example for updating NetBSD’s mtree that is in our tree. The vendor branch for this is vendor/NetBSD/mtree.

5.4.2. Updating an old vendor import

The vendor trees usually have only the subset of the third-party software that is appropriate to FreeBSD. These trees are usually tiny in comparison to the FreeBSD tree. Git worktrees are thus quite small and fast and the preferred method to use. Make sure that whatever directory you choose below (the ../mtree) does not currently exist.

% git worktree add ../mtree vendor/NetBSD/mtree

5.4.3. Update the Sources in the Vendor Branch

Prepare a full, clean tree of the vendor sources. Import everything but merge only what is needed.

This example assumes the NetBSD source is checked out from their GitHub mirror in ~/git/NetBSD. Note that "upstream" might have added or removed files, so we want to make sure deletions are propagated as well. net/rsync is commonly installed, so I’ll use that.

% cd ../mtree
% rsync -va --del --exclude=".git" ~/git/NetBSD/usr.sbin/mtree/ .
% git add -A
% git status
...
% git diff --staged
...
% git commit -m "Vendor import of NetBSD's mtree at 2020-12-11"
[vendor/NetBSD/mtree 8e7aa25fcf1] Vendor import of NetBSD's mtree at 2020-12-11
 7 files changed, 114 insertions(+), 82 deletions(-)
% git tag -a vendor/NetBSD/mtree/20201211

It is critical to verify that the source code you are importing comes from a trustworthy source. Many open-source projects use cryptographic signatures to sign code changes, git tags, and/or source code tarballs. Always verify these signatures, and use isolation mechanisms like jails, chroot, in combination with a dedicated, non-privileged user account that is different from the one you regularly use (see the Updating the FreeBSD source tree section below for more details), until you are confident that the source code you are importing looks safe. Following the upstream development and occasionally reviewing the upstream code changes can greatly help in improving code quality and benefit everyone involved. It is also a good idea to examine the git diff results before importing them into the vendor area.

Always run the git diff and git status commands and examine the results carefully. When in doubt, it is useful to do a git annotate on the vendor branch or the upstream git repository to see who and why a change was made.

In the example above we used -m to illustrate, but you should compose a proper message in an editor (using a commit message template).

It is also important to create an annotated tag using git tag -a, otherwise the push will be rejected. Only annotated tags are allowed to be pushed. The annotated tag gives you a chance to enter a commit message. Enter the version you are importing, along with any salient new features or fixes in that version.

5.4.4. Updating the FreeBSD Copy

At this point you can push the import to vendor into our repo.

% git push --follow-tags freebsd vendor/NetBSD/mtree

--follow-tags tells git push to also push tags associated with the locally committed revision.

5.4.5. Updating the FreeBSD source tree

Now you need to update the mtree in FreeBSD. The sources live in contrib/mtree since it is upstream software.

From time to time, we may have to make changes to the contributed code to better satisfy FreeBSD’s needs. Whenever possible, please try to contribute the local changes back to the upstream projects, this helps them to better support FreeBSD, and also saves your time for future conflict resolutions when importing updates.

% cd ../src
% git subtree merge -P contrib/mtree vendor/NetBSD/mtree

This would generate a subtree merge commit of contrib/mtree against the local vendor/NetBSD/mtree branch. Examine the diff from the merge result and the contents of the upstream branch. If the merge reduced our local changes to more trivial difference like blank line or indenting changes, try amending the local changes to reduce diff against upstream, or try to contribute the remaining changes back to the upstream project. If there were conflicts, you would need to fix them before committing. Include details about the changes being merged in the merge commit message.

Some open-source software includes a configure script that generates files used to define how the code is built; usually, these generated files like config.h should be updated as part of the import process. When doing this, always keep in mind that these scripts are executable code running under the current user’s credentials. This process should always be run in an isolated environment, ideally inside a jail that does not have network access, and with an unprivileged account; or, at minimum, a dedicated account that is different from the user account you normally use for everyday purposes or for pushing to the FreeBSD source code repository. This minimizes the risk of encountering bugs that can cause data loss or, in worse cases, maliciously planted code. Using an isolated jail also prevents the configure scripts from detecting locally installed software packages, which may lead to unexpected results.

When testing your changes, run them in a chroot or jailed environment, or even within a virtual machine first, especially for kernel or library modifications. This approach helps prevent adverse interactions with your working environment. It can be particularly beneficial for changes to libraries that many base system components use, among others.

5.4.6. Rebasing your change against latest FreeBSD source tree

Because the current policy recommends against using merges, if the upstream FreeBSD main moved forward before you get a chance to push, you would have to redo the merge.

Regular git rebase or git pull --rebase doesn’t know how to rebase a merge commit as a merge commit, so instead of that you would have to recreate the commit.

The following steps should be taken to easily recreate the merge commit as if git rebase --merge-commits worked properly:

The commands one would use, following the above example of mtree, would be like so (the # starts a comment to help link commands to descriptions above):

% cd ../src			# CD to top of tree
% git checkout -b XXX		# create new throw-away XXX branch for merge
% git fetch freebsd		# Get changes from upstream from upstream
% git merge freebsd/main	# Merge the changes and resolve conflicts
% git checkout -b YYY freebsd/main # Create new throw-away YYY branch for redo
% git subtree merge -P contrib/mtree vendor/NetBSD/mtree # Redo subtree merge
% git checkout XXX .		# XXX branch has the conflict resolution
% git commit -c XXX~1		# -c reuses the commit message from commit before rebase
% git diff XXX YYY		# Should be empty
% git show YYY			# Should only have changes you want, and be a merge commit from vendor branch

Note: if things go wrong with the commit, you can reset the YYY branch by reissuing the checkout command that created it with -B to start over:

% git checkout -B YYY freebsd/main # Create new throw-away YYY branch if starting over is just going to be easier

5.4.7. Pushing the changes

Once you think you have a set of changes that are good, you can push it to a fork off GitHub or GitLab for others to review. One nice thing about Git is that it allows you to publish rough drafts of your work for others to review. While Phabricator is good for content review, publishing the updated vendor branch and merge commits lets others check the details as they will eventually appear in the repository.

After review, when you are sure it is a good change, you can push it to the FreeBSD repo:

% git push freebsd YYY:main	# put the commit on upstream's 'main' branch
% git branch -D XXX		# Throw away the throw-a-way branches.
% git branch -D YYY

Note: I used XXX and YYY to make it obvious they are terrible names and should not leave your machine. If you use such names for other work, then you’ll need to pick different names, or risk losing the other work. There is nothing magic about these names. Upstream will not allow you to push them, but never the less, please pay attention to the exact commands above. Some commands use syntax that differs only slightly from typical uses and that different behavior is critical to this recipe working.

5.4.8. How to redo things if need be

If you’ve tried to do the push in the previous section and it fails, then you should do the following to 'redo' things. This sequence keeps the commit with the commit message always at XXX~1 to make committing easier.

% git checkout -B XXX YYY	# recreate that throw-away-branch XXX and switch to it
% git merge freebsd/main	# Merge the changes and resolve conflicts
% git checkout -B YYY freebsd/main # Recreate new throw-away YYY branch for redo
% git subtree merge -P contrib/mtree vendor/NetBSD/mtree # Redo subtree merge
% git checkout XXX .		# XXX branch has the conflict resolution
% git commit -c XXX~1		# -c reuses the commit message from commit before rebase

Then go check it out as above and push as above when ready.

5.5.1. Create the repo

% cd /some/where
% mkdir glorbnitz
% cd glorbnitz
% git init
% git checkout -b vendor/glorbnitz

At this point, you have a new repo, where all new commits will go on the vendor/glorbnitz branch.

Git experts can also do this right in their FreeBSD clone, using git checkout --orphan vendor/glorbnitz if they are more comfortable with that.

5.5.2. Copy the sources in

Since this is a new import, you can just cp the sources in, or use tar or even rsync as shown above. And we will add everything, assuming no dot files.

% cp -r ~/glorbnitz/* .
% git add *

At this point, you should have a pristine copy of glorbnitz ready to commit.

% git commit -m "Import GlorbNitz frobnosticator revision 3.1415"

As above, I used -m for simplicity, but you should likely create a commit message that explains what a Glorb is and why you’d use a Nitz to get it. Not everybody will know so, for your actual commit, you should follow the commit log message section instead of emulating the brief style used here.

5.5.3. Now import it into our repository

Now you need to import the branch into our repository.

% cd /path/to/freebsd/repo/src
% git remote add glorbnitz /some/where/glorbnitz
% git fetch glorbnitz vendor/glorbnitz

Note the vendor/glorbnitz branch is in the repo. At this point the /some/where/glorbnitz can be deleted, if you like. It was only a means to an end.

5.5.4. Tag and push

Steps from here on out are much the same as they are in the case of updating a vendor branch, though without the updating the vendor branch step.

% git worktree add ../glorbnitz vendor/glorbnitz
% cd ../glorbnitz
% git tag --annotate vendor/glorbnitz/3.1415
# Make sure the commit is good with "git show"
% git push --follow-tags freebsd vendor/glorbnitz

By 'good' we mean:

5.5.5. Time to finally merge it into the base tree

% cd ../src
% git subtree add -P contrib/glorbnitz vendor/glorbnitz
# Make sure the commit is good with "git show"
% git commit --amend   # one last sanity check on commit message
% git push freebsd

Here 'good' means:

% git config --global pull.ff only

% cd freebsd-src
% git checkout main
% git pull (--ff-only|--rebase)

% cd freebsd-src
% git checkout main
% git fetch freebsd
% git merge --ff-only freebsd/main

% git rebase -i main working

% git remote set-url --push freebsd ssh://git@gitrepo.freebsd.org/src.git

freefall% gen-gitconfig.sh

% git push freebsd working:main

% git checkout working
% git fetch freebsd
% git rebase freebsd/main
% git push freebsd working:main

% git checkout main
% git merge --ff-only `working`
% git push freebsd

% git pull --rebase
% git push freebsd

% git log --grep revision=XXXX

5.6.1. Users

% git clone -o freebsd --config remote.freebsd.fetch='+refs/notes/*:refs/notes/*' $URL freebsd-current

% cd freebsd-current
% git worktree add ../freebsd-stable-12 stable/12

% cd freebsd-current
% git checkout main
% git pull --ff-only
# changes from upstream now local and current tree updated
% cd ../freebsd-stable-12
% git merge --ff-only freebsd/stable/12
# now your stable/12 is up to date too

5.6.2. Developers

% git branch issue                # Create the 'issue' branch
% git reset --hard freebsd/main   # Reset 'main' back to the official tip
% git checkout issue              # Back to where you were

# We're on branch wilma
% git checkout fred		# move to fred branch
% git cherry-pick wilma		# copy the misplaced commit
% git checkout wilma		# go back to wilma branch
% git reset --hard HEAD^	# move what wilma refers to back 1 commit

% git checkout pre-split	# Go back
% git branch -D fred		# delete the fred branch
% git checkout -B wilma		# reset the wilma branch
% git branch -d pre-split	# Pretend it didn't happen

% git reflog
6ff9c25 (HEAD -> wilma) HEAD@{0}: rebase -i (finish): returning to refs/heads/wilma
6ff9c25 (HEAD -> wilma) HEAD@{1}: rebase -i (start): checkout main
869cbd3 HEAD@{2}: rebase -i (start): checkout wilma
a6a5094 (fred) HEAD@{3}: rebase -i (finish): returning to refs/heads/fred
a6a5094 (fred) HEAD@{4}: rebase -i (pick): Encourage contributions
1ccd109 (freebsd/main, main) HEAD@{5}: rebase -i (start): checkout main
869cbd3 HEAD@{6}: rebase -i (start): checkout fred
869cbd3 HEAD@{7}: checkout: moving from wilma to fred
869cbd3 HEAD@{8}: commit: Encourage contributions
...
%

% git checkout -B wilma 869cbd3
% git branch -D fred

% git checkout 869cbd3
M	faq.md
Note: checking out '869cbd3'.
You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by performing another checkout.
If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -b with the checkout command again. Example:
  git checkout -b <new-branch-name>
HEAD is now at 869cbd3 Encourage contributions
% git checkout -B wilma

git log --oneline HEAD^1   # Look at the first parent's commits
git log --oneline HEAD^2   # Look at the second parent's commits

git branch -f main freebsd/main

% git checkout worker
% git checkout -b feature	# create a new branch
% git cherry-pick main..async	# bring in the changes

% git checkout driver		# Checkout the driver
% git checkout -b kernel	# Create kernel branch
% git checkout -b userland	# Create userland branch

% git rebase -i main kernel

% git rebase -i main userland

% git checkout kernel
% git log driver
% git cherry-pick $HASH

5.6.3. Cloning and Mirroring

Q: I’d like to mirror the entire Git repository, how do I do that?

A: If all you want to do is mirror, then

% git clone --mirror $URL

will do the trick. However, there are two disadvantages to this if you want to use it for anything other than a mirror you’ll reclone.

First, this is a 'bare repository' which has the repository database, but no checked out worktree. This is great for mirroring, but terrible for day to day work. There’s a number of ways around this with git worktree:

% git clone --mirror https://git.freebsd.org/ports.git ports.git
% cd ports.git
% git worktree add ../ports main
% git worktree add ../quarterly branches/2020Q4
% cd ../ports

But if you aren’t using your mirror for further local clones, then it’s a poor match.

The second disadvantage is that Git normally rewrites the refs (branch name, tags, etc) from upstream so that your local refs can evolve independently of upstream. This means that you’ll lose changes if you are committing to this repository on anything other than private project branches.

Q: So what can I do instead?

A: Well, you can stuff all of the upstream repository’s refs into a private namespace in your local repository. Git clones everything via a 'refspec' and the default refspec is:

        fetch = +refs/heads/*:refs/remotes/freebsd/*

which says just fetch the branch refs.

However, the FreeBSD repository has a number of other things in it. To see those, you can add explicit refspecs for each ref namespace, or you can fetch everything. To setup your repository to do that:

git config --add remote.freebsd.fetch '+refs/*:refs/freebsd/*'

which will put everything in the upstream repository into your local repository’s refs/freebsd/ namespace. Please note, that this also grabs all the unconverted vendor branches and the number of refs associated with them is quite large.

You’ll need to refer to these 'refs' with their full name because they aren’t in and of Git’s regular namespaces.

git log refs/freebsd/vendor/zlib/1.2.10

would look at the log for the vendor branch for zlib starting at 1.2.10.

````
% git remote -v
freebsd https://git.freebsd.org/src.git (fetch)
freebsd ssh://git@gitrepo.freebsd.org/src.git (push)
````

% git remote add github git@github.com:gvnn3/freebsd-src.git
% git remote -v
github	git@github.com:gvnn3/freebsd-src.git (fetch)
github	git@github.com:gvnn3/freebsd-src.git (push)
freebsd	https://git.freebsd.org/src.git (fetch)
freebsd	ssh://git@gitrepo.freebsd.org/src.git (push)

% git checkout -b gnn-pr2001-fix

% git push github
fatal: The current branch gnn-pr2001-fix has no upstream branch.
To push the current branch and set the remote as upstream, use
    git push --set-upstream github gnn-pr2001-fix

% git push --set-upstream github gnn-feature
Enumerating objects: 20486, done.
Counting objects: 100% (20486/20486), done.
Delta compression using up to 8 threads
Compressing objects: 100% (12202/12202), done.
Writing objects: 100% (20180/20180), 56.25 MiB | 13.15 MiB/s, done.
Total 20180 (delta 11316), reused 12972 (delta 7770), pack-reused 0
remote: Resolving deltas: 100% (11316/11316), completed with 247 local objects.
remote:
remote: Create a pull request for 'gnn-feature' on GitHub by visiting:
remote:      https://github.com/gvnn3/freebsd-src/pull/new/gnn-feature
remote:
To github.com:gvnn3/freebsd-src.git
 * [new branch]                gnn-feature -> gnn-feature
Branch 'gnn-feature' set up to track remote branch 'gnn-feature' from 'github'.

% git push
Enumerating objects: 4, done.
Counting objects: 100% (4/4), done.
Delta compression using up to 8 threads
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 314 bytes | 1024 bytes/s, done.
Total 3 (delta 1), reused 1 (delta 0), pack-reused 0
remote: Resolving deltas: 100% (1/1), completed with 1 local object.
To github.com:gvnn3/freebsd-src.git
   9e5243d7b659..cf6aeb8d7dda  gnn-feature -> gnn-feature

% git remote -v
freebsd https://git.freebsd.org/src.git (fetch)
freebsd ssh://git@gitrepo.freebsd.org/src.git (push)
github https://github.com/freebsd/freebsd-src (fetch)
github https://github.com/freebsd/freebsd-src (fetch)

% git fetch github pull/$PR/head:staging
% git rebase -i main staging	# to move the staging branch forward, adjust commit message here
<do testing here, as needed>
% git checkout main
% git pull --ff-only		# to get the latest if time has passed
% git checkout main
% git merge --ff-only staging
<test again if needed>
% git push freebsd --push-option=confirm-author

For complicated pull requests that have multiple commits with conflicts, follow the following outline.

This will also work when bringing branches developed elsewhere into the local tree for committing.

• Get mentor approval before committing each of these changes!

• All src commits go to FreeBSD-CURRENT first before being merged to FreeBSD-STABLE. The FreeBSD-STABLE branch must maintain ABI and API compatibility with earlier versions of that branch. Do not merge changes that break this compatibility.

Steps for New Committers

1. Introduce yourself to the other developers, otherwise no one will have any idea who you are or what you are working on. The introduction need not be a comprehensive biography, just write a paragraph or two about who you are, what you plan to be working on as a developer in FreeBSD, and who will be your mentor. Email this to the FreeBSD developers mailing list and you will be on your way!

2. Log into freefall.FreeBSD.org and create a /var/forward/user (where user is your username) file containing the e-mail address where you want mail addressed to yourusername@FreeBSD.org to be forwarded. This includes all of the commit messages as well as any other mail addressed to the FreeBSD committer’s mailing list and the FreeBSD developers mailing list. Really large mailboxes which have taken up permanent residence on freefall may get truncated without warning if space needs to be freed, so forward it or save it elsewhere.

   If your e-mail system uses SPF with strict rules, you should exclude mx2.FreeBSD.org from SPF checks.

   Due to the severe load dealing with SPAM places on the central mail servers that do the mailing list processing, the front-end server does do some basic checks and will drop some messages based on these checks. At the moment proper DNS information for the connecting host is the only check in place but that may change. Some people blame these checks for bouncing valid email. To have these checks turned off for your email, create a file named ~/.spam_lover on freefall.FreeBSD.org.

   Those who are developers but not committers will not be subscribed to the committers or developers mailing lists. The subscriptions are derived from the access rights.

7.2.1. SMTP Access Setup

For those willing to send e-mail messages through the FreeBSD.org infrastructure, follow the instructions below:

sender_dependent_relayhost_maps = hash:/usr/local/etc/postfix/relayhost_maps
smtp_sasl_auth_enable = yes
smtp_sasl_security_options = noanonymous
smtp_sasl_password_maps = hash:/usr/local/etc/postfix/sasl_passwd
smtp_use_tls = yes

yourusername@FreeBSD.org  [smtp.freebsd.org]:587

[smtp.freebsd.org]:587          yourusername:yourpassword

smtpd_sender_login_maps = hash:/usr/local/etc/postfix/sender_login_maps
smtpd_sender_restrictions = reject_known_sender_login_mismatch

yourusername@FreeBSD.org yourlocalusername

action "freebsd" relay host smtp+tls://freebsd@smtp.freebsd.org:587 auth <secrets>
match from any auth yourlocalusername mail-from "_yourusername_@freebsd.org" for any action "freebsd"

freebsd	yourusername:yourpassword

Routers section: (at the top of the list):
freebsd_send:
   driver = manualroute
   domains = !+local_domains
   transport = freebsd_smtp
   route_data = ${lookup {${lc:$sender_address}} lsearch {/usr/local/etc/exim/freebsd_send}}
Transport Section:
freebsd_smtp:
        driver = smtp
  tls_certificate=<local certificate>
  tls_privatekey=<local certificate private key>
  tls_require_ciphers = EECDH+ECDSA+AESGCM:EECDH+aRSA+AESGCM:EECDH+ECDSA+SHA384:EECDH+ECDSA+SHA256:EECDH+aRSA+SHA384:EECDH+aRSA+SHA256:EECDH+AESGCM:EECDH:EDH+AESGCM:EDH+aRSA:HIGH:!MEDIUM:!LOW:!aNULL:!eNULL:!LOW:!RC4:!MD5:!EXP:!PSK:!SRP:!DSS
  dkim_domain = <local DKIM domain>
  dkim_selector = <local DKIM selector>
  dkim_private_key= <local DKIM private key>
  dnssec_request_domains = *
  hosts_require_auth = smtp.freebsd.org
Authenticators:
freebsd_plain:
  driver = plaintext
  public_name = PLAIN
  client_send = ^example/mail^examplePassword
  client_condition = ${if eq{$host}{smtp.freebsd.org}}

example@freebsd.org:smtp.freebsd.org::587

• Communicating with other developers

  FreeBSD commits generate email to various mailing lists. These include the commit message along with a copy of the patch itself. Commit messages are also viewed through commands like git log. These serve to make other developers aware of changes that are ongoing; that other developer may want to test the change, may have an interest in the topic and will want to review in more detail, or may have their own projects underway that would benefit from interaction.

• Making Changes Discoverable

  In a large project with a long history it may be difficult to find changes of interest when investigating an issue or change in behaviour. Verbose, detailed commit messages allow searches for changes that might be relevant. For example, git log --since 1year --grep 'USB timeout'.

• Providing historical documentation

  Commit messages serve to document changes for future developers, perhaps years or decades later. This future developer may even be you, the original author. A change that seems obvious today may be decidedly not so much later on.

Example 4. Commit Log for a Commit Based on a PR

Example 5. Commit Log for a Commit Needing Review

Example 6. Commit Log for a Commit Needing Approval

...
Approved by:	abc (maintainer)

Example 7. Commit Log for a Commit Bringing in Code from OpenBSD

...
Obtained from:	OpenBSD

Example 8. Commit Log for a Change to FreeBSD-CURRENT with a Planned Commit to FreeBSD-STABLE to Follow at a Later Date.

Example 9. Example Combined Commit Log

PR:		54321
Reviewed by:	-arch
Obtained from:	NetBSD
MFC after:	1 month
Relnotes:	yes

1. Respect other committers.

   This means that you need to treat other committers as the peer-group developers that they are. Despite our occasional attempts to prove the contrary, one does not get to be a committer by being stupid and nothing rankles more than being treated that way by one of your peers. Whether we always feel respect for one another or not (and everyone has off days), we still have to treat other committers with respect at all times, on public forums and in private email.

   Being able to work together long term is this project’s greatest asset, one far more important than any set of changes to the code, and turning arguments about code into issues that affect our long-term ability to work harmoniously together is just not worth the trade-off by any conceivable stretch of the imagination.

   To comply with this rule, do not send email when you are angry or otherwise behave in a manner which is likely to strike others as needlessly confrontational. First calm down, then think about how to communicate in the most effective fashion for convincing the other persons that your side of the argument is correct, do not just blow off some steam so you can feel better in the short term at the cost of a long-term flame war. Not only is this very bad "energy economics", but repeated displays of public aggression which impair our ability to work well together will be dealt with severely by the project leadership and may result in suspension or termination of your commit privileges. The project leadership will take into account both public and private communications brought before it. It will not seek the disclosure of private communications, but it will take it into account if it is volunteered by the committers involved in the complaint.

   All of this is never an option which the project’s leadership enjoys in the slightest, but unity comes first. No amount of code or good advice is worth trading that away.

2. Respect other contributors.

   You were not always a committer. At one time you were a contributor. Remember that at all times. Remember what it was like trying to get help and attention. Do not forget that your work as a contributor was very important to you. Remember what it was like. Do not discourage, belittle, or demean contributors. Treat them with respect. They are our committers in waiting. They are every bit as important to the project as committers. Their contributions are as valid and as important as your own. After all, you made many contributions before you became a committer. Always remember that.

3. Discuss any significant change before committing.

   The repository is not where changes are initially submitted for correctness or argued over, that happens first in the mailing lists or by use of the Phabricator service. The commit will only happen once something resembling consensus has been reached. This does not mean that permission is required before correcting every obvious syntax error or manual page misspelling, just that it is good to develop a feel for when a proposed change is not quite such a no-brainer and requires some feedback first. People really do not mind sweeping changes if the result is something clearly better than what they had before, they just do not like being surprised by those changes. The very best way of making sure that things are on the right track is to have code reviewed by one or more other committers.

   When in doubt, ask for review!

4. Respect existing maintainers if listed.

   Many parts of FreeBSD are not "owned" in the sense that any specific individual will jump up and yell if you commit a change to "their" area, but it still pays to check first. One convention we use is to put a maintainer line in the Makefile for any package or subtree which is being actively maintained by one or more people; see Source Tree Guidelines and Policies for documentation on this. Where sections of code have several maintainers, commits to affected areas by one maintainer need to be reviewed by at least one other maintainer. In cases where the "maintainer-ship" of something is not clear, look at the repository logs for the files in question and see if someone has been working recently or predominantly in that area.

5. Any disputed change must be backed out pending resolution of the dispute if requested by a maintainer. Security related changes may override a maintainer’s wishes at the Security Officer’s discretion.

   This may be hard to swallow in times of conflict (when each side is convinced that they are in the right, of course) but a version control system makes it unnecessary to have an ongoing dispute raging when it is far easier to simply reverse the disputed change, get everyone calmed down again and then try to figure out what is the best way to proceed. If the change turns out to be the best thing after all, it can be easily brought back. If it turns out not to be, then the users did not have to live with the bogus change in the tree while everyone was busily debating its merits. People very rarely call for back-outs in the repository since discussion generally exposes bad or controversial changes before the commit even happens, but on such rare occasions the back-out should be done without argument so that we can get immediately on to the topic of figuring out whether it was bogus or not.

6. Changes go to FreeBSD-CURRENT before FreeBSD-STABLE unless specifically permitted by the release engineer or unless they are not applicable to FreeBSD-CURRENT. Any non-trivial or non-urgent change which is applicable should also be allowed to sit in FreeBSD-CURRENT for at least 3 days before merging so that it can be given sufficient testing. The release engineer has the same authority over the FreeBSD-STABLE branch as outlined in rule #5.

   This is another "do not argue about it" issue since it is the release engineer who is ultimately responsible (and gets beaten up) if a change turns out to be bad. Please respect this and give the release engineer your full cooperation when it comes to the FreeBSD-STABLE branch. The management of FreeBSD-STABLE may frequently seem to be overly conservative to the casual observer, but also bear in mind the fact that conservatism is supposed to be the hallmark of FreeBSD-STABLE and different rules apply there than in FreeBSD-CURRENT. There is also really no point in having FreeBSD-CURRENT be a testing ground if changes are merged over to FreeBSD-STABLE immediately. Changes need a chance to be tested by the FreeBSD-CURRENT developers, so allow some time to elapse before merging unless the FreeBSD-STABLE fix is critical, time sensitive or so obvious as to make further testing unnecessary (spelling fixes to manual pages, obvious bug/typo fixes, etc.) In other words, apply common sense.

   Changes to the security branches (for example, releng/9.3) must be approved by a member of the Security Officer Team <security-officer@FreeBSD.org>, or in some cases, by a member of the Release Engineering Team <re@FreeBSD.org>.

7. Do not fight in public with other committers; it looks bad.

   This project has a public image to uphold and that image is very important to all of us, especially if we are to continue to attract new members. There will be occasions when, despite everyone’s very best attempts at self-control, tempers are lost and angry words are exchanged. The best thing that can be done in such cases is to minimize the effects of this until everyone has cooled back down. Do not air angry words in public and do not forward private correspondence or other private communications to public mailing lists, mail aliases, instant messaging channels or social media sites. What people say one-to-one is often much less sugar-coated than what they would say in public, and such communications therefore have no place there - they only serve to inflame an already bad situation. If the person sending a flame-o-gram at least had the grace to send it privately, then have the grace to keep it private yourself. If you feel you are being unfairly treated by another developer, and it is causing you anguish, bring the matter up with core rather than taking it public. Core will do its best to play peace makers and get things back to sanity. In cases where the dispute involves a change to the codebase and the participants do not appear to be reaching an amicable agreement, core may appoint a mutually-agreeable third party to resolve the dispute. All parties involved must then agree to be bound by the decision reached by this third party.

8. Respect all code freezes and read the committers and developers mailing list on a timely basis so you know when a code freeze is in effect.

   Committing unapproved changes during a code freeze is a really big mistake and committers are expected to keep up-to-date on what is going on before jumping in after a long absence and committing 10 megabytes worth of accumulated stuff. People who abuse this on a regular basis will have their commit privileges suspended until they get back from the FreeBSD Happy Reeducation Camp we run in Greenland.

9. When in doubt on any procedure, ask first!

   Many mistakes are made because someone is in a hurry and just assumes they know the right way of doing something. If you have not done it before, chances are good that you do not actually know the way we do things and really need to ask first or you are going to completely embarrass yourself in public. There is no shame in asking "how in the heck do I do this?" We already know you are an intelligent person; otherwise, you would not be a committer.

10. Test your changes before committing them.

    If your changes are to the kernel, make sure you can still compile both GENERIC and LINT. If your changes are anywhere else, make sure you can still make world. If your changes are to a branch, make sure your testing occurs with a machine which is running that code. If you have a change which also may break another architecture, be sure and test on all supported architectures. Please ensure your change works for supported toolchains. Please refer to the FreeBSD Internal Page for a list of available resources. As other architectures are added to the FreeBSD supported platforms list, the appropriate shared testing resources will be made available.

11. Do not commit to contributed software without explicit approval from the respective maintainers.

    Contributed software is anything under the src/contrib, src/crypto, or src/sys/contrib trees.

    The trees mentioned above are for contributed software usually imported onto a vendor branch. Committing something there may cause unnecessary headaches when importing newer versions of the software. As a general consider sending patches upstream to the vendor. Patches may be committed to FreeBSD first with permission of the maintainer.

    Reasons for modifying upstream software range from wanting strict control over a tightly coupled dependency to lack of portability in the canonical repository’s distribution of their code. Regardless of the reason, effort to minimize the maintenance burden of fork is helpful to fellow maintainers. Avoid committing trivial or cosmetic changes to files since it makes every merge thereafter more difficult: such patches need to be manually re-verified every import.

    If a particular piece of software lacks a maintainer, you are encouraged to take up ownership. If you are unsure of the current maintainership email FreeBSD architecture and design mailing list and ask.

20.3.1. Current Compiler Versions

The in-tree compiler is currently Clang 15.x. Currently, GCC 12 and Clang 12, 13, 14 and 15 are tested in the github and project’s CI jenkins jobs. Work is underway to get the tree ready for Clang 16. The oldest project supported branch has Clang 12, so the bootstrap portions of the build must work for Clang major versions 12 to 15.

1. Mention is made in the manual page and possibly the release notes that the option, utility, or interface is deprecated. Use of the deprecated feature generates a warning.

2. The option, utility, or interface is preserved until the next major (point zero) release.

3. The option, utility, or interface is removed and no longer documented. It is now obsolete. It is also generally a good idea to note its removal in the release notes.

1. Most FreeBSD business is done in public.

   FreeBSD is an open project. Which means that not only can anyone use the source code, but that most of the development process is open to public scrutiny.

2. Certain sensitive matters must remain private or held under embargo.

   There unfortunately cannot be complete transparency. As a FreeBSD developer you will have a certain degree of privileged access to information. Consequently you are expected to respect certain requirements for confidentiality. Sometimes the need for confidentiality comes from external collaborators or has a specific time limit. Mostly though, it is a matter of not releasing private communications.

3. The Security Officer has sole control over the release of security advisories.

   Where there are security problems that affect many different operating systems, FreeBSD frequently depends on early access to be able to prepare advisories for coordinated release. Unless FreeBSD developers can be trusted to maintain security, such early access will not be made available. The Security Officer is responsible for controlling pre-release access to information about vulnerabilities, and for timing the release of all advisories. He may request help under condition of confidentiality from any developer with relevant knowledge to prepare security fixes.

4. Communications with Core are kept confidential for as long as necessary.

   Communications to core will initially be treated as confidential. Eventually however, most of Core’s business will be summarized into the monthly or quarterly core reports. Care will be taken to avoid publicising any sensitive details. Records of some particularly sensitive subjects may not be reported on at all and will be retained only in Core’s private archives.

5. Non-disclosure Agreements may be required for access to certain commercially sensitive data.

   Access to certain commercially sensitive data may only be available under a Non-Disclosure Agreement. The FreeBSD Foundation legal staff must be consulted before any binding agreements are entered into.

6. Private communications must not be made public without permission.

   Beyond the specific requirements above there is a general expectation not to publish private communications between developers without the consent of all parties involved. Ask permission before forwarding a message onto a public mailing list, or posting it to a forum or website that can be accessed by other than the original correspondents.

7. Communications on project-only or restricted access channels must be kept private.

   Similarly to personal communications, certain internal communications channels, including FreeBSD Committer only mailing lists and restricted access IRC channels are considered private communications. Permission is required to publish material from these sources.

8. Core may approve publication.

   Where it is impractical to obtain permission due to the number of correspondents or where permission to publish is unreasonably withheld, Core may approve release of such private matters that merit more general publication.

21.2.1. Tier 1: Fully-Supported Architectures

Tier 1 platforms are the most mature FreeBSD platforms. They are supported by the security officer, release engineering, and Ports Management Team. Tier 1 architectures are expected to be Production Quality with respect to all aspects of the FreeBSD operating system, including installation and development environments.

The FreeBSD Project provides the following guarantees to consumers of Tier 1 platforms:

To maintain maturity of Tier 1 platforms, the FreeBSD Project will maintain the following resources to support development:

Collectively, developers are required to provide the following to maintain the Tier 1 status of a platform:

21.2.2. Tier 2: Developmental and Niche Architectures

Tier 2 platforms are functional, but less mature FreeBSD platforms. They are not supported by the security officer, release engineering, and Ports Management Team.

Tier 2 platforms may be Tier 1 platform candidates that are still under active development. Architectures reaching end of life may also be moved from Tier 1 status to Tier 2 status as the availability of resources to continue to maintain the system in a Production Quality state diminishes. Well-supported niche architectures may also be Tier 2.

The FreeBSD Project provides the following guarantees to consumers of Tier 2 platforms:

To maintain maturity of Tier 2 platforms, the FreeBSD Project will maintain the following resources to support development:

Collectively, developers are required to provide the following to maintain the Tier 2 status of a platform:

21.2.3. Tier 3: Experimental Architectures

Tier 3 platforms have at least partial FreeBSD support. They are not supported by the security officer, release engineering, and Ports Management Team.

Tier 3 platforms are architectures in the early stages of development, for non-mainstream hardware platforms, or which are considered legacy systems unlikely to see broad future use. Initial support for Tier 3 platforms may exist in a separate repository rather than the main source repository.

The FreeBSD Project provides no guarantees to consumers of Tier 3 platforms and is not committed to maintaining resources to support development. Tier 3 platforms may not always be buildable, nor are any kernel or userland ABIs considered stable.

21.2.4. Unsupported Architectures

Other platforms are not supported in any form by the project. The project previously described these as Tier 4 systems.

After a platform transitions to unsupported, all support for the platform is removed from the source, ports and documentation trees. Note that ports support should remain as long as the platform is supported in a branch supported by ports.

22.1.1. How do I add a new port?

Adding a port to the tree is relatively simple. Once the port is ready to be added, as explained later here, you need to add the port’s directory entry in the category’s Makefile. In this Makefile, ports are listed in alphabetical order and added to the SUBDIR variable, like this:

Once the port and its category’s Makefile are ready, the new port can be committed:

% git add category/Makefile category/newport
% git commit
% git push

Check the port, preferably to make sure it compiles and packages correctly.

You do not necessarily have to eliminate all warnings but make sure you have fixed the simple ones.

If the port came from a submitter who has not contributed to the Project before, add that person’s name to the Additional Contributors section of the FreeBSD Contributors List.

Close the PR if the port came in as a PR. To close a PR, change the state to Issue Resolved and the resolution as Fixed.

# make install
# make package
# make deinstall
# pkg add package you built above
# make deinstall
# make reinstall
# make package

22.2.1. How do I remove an existing port?

First, please read the section about repository copies. Before you remove the port, you have to verify there are no other ports depending on it.

Alternatively, you can use the rmport script, from ports/Tools/scripts. This script was written by Vasil Dimov <vd@FreeBSD.org>. When sending questions about this script to the FreeBSD ports mailing list, please also CC Chris Rees <crees@FreeBSD.org>, the current maintainer.

1. Perform a thorough check of the ports collection for any dependencies on the old port location/name, and update them. Running grep on INDEX is not enough because some ports have dependencies enabled by compile-time options. A full git-grep(1) of the ports collection is recommended.

2. Remove the SUBDIR entry from the old category Makefile and add a SUBDIR entry to the new category Makefile.

3. Add an entry to ports/MOVED.

4. Search for entries in xml files inside ports/security/vuxml and adjust them accordingly. In particular, check for previous packages with the new name which version could include the new port.

5. Move the port with git mv.

6. Commit the changes.

1. Copy port with cp -R old-cat/old-port new-cat/new-port.

2. Add the new port to the new-cat/Makefile.

3. Change stuff in new-cat/new-port.

4. Commit the changes.

22.5.1. What is a “ports freeze”?

A “ports freeze” was a restricted state the ports tree was put in before a release. It was used to ensure a higher quality for the packages shipped with a release. It usually lasted a couple of weeks. During that time, build problems were fixed, and the release packages were built. This practice is no longer used, as the packages for the releases are built from the current stable, quarterly branch.

22.6.1. What is the procedure to request authorization for merging a commit to the quarterly branch?

As of November 30, 2020, there is no need to seek explicit approval to commit to the quarterly branch.

22.6.2. What is the procedure for merging commits to the quarterly branch?

Merging commits to the quarterly branch (a process we call MFH for a historical reason) is very similar to MFC’ing a commit in the src repository, so basically:

% git checkout 2021Q2
% git cherry-pick -x $HASH
(verify everything is OK, for example by doing a build test)
% git push

where $HASH is the hash of the commit you want to copy over to the quarterly branch. The -x parameter ensures the hash $HASH of the main branch is included in the new commit message of the quarterly branch.

22.7.1. What is the procedure for creating a new category?

Please see Proposing a New Category in the Porter’s Handbook. Once that procedure has been followed and the PR has been assigned to the Ports Management Team <portmgr@FreeBSD.org>, it is their decision whether or not to approve it. If they do, it is their responsibility to:

22.7.2. What do I need to do to implement a new physical category?

22.7.3. What do I need to do to implement a new virtual category?

This is much simpler than a physical category. Only a few modifications are needed:

22.8.1. Are there changes that can be committed without asking the maintainer for approval?

Blanket approval for most ports applies to these types of fixes:

22.8.2. How do I know if my port is building correctly or not?

The packages are built multiple times each week. If a port fails, the maintainer will receive an email from pkg-fallout@FreeBSD.org.

Reports for all the package builds (official, experimental, and non-regression) are aggregated at pkg-status.FreeBSD.org.

22.8.3. I added a new port. Do I need to add it to the INDEX?

No. The file can either be generated by running make index, or a pre-generated version can be downloaded with make fetchindex.

22.8.4. Are there any other files I am not allowed to touch?

Any file directly under ports/, or any file under a subdirectory that starts with an uppercase letter (Mk/, Tools/, etc.). In particular, the Ports Management Team <portmgr@FreeBSD.org> is very protective of ports/Mk/bsd.port*.mk so do not commit changes to those files unless you want to face their wrath.

22.8.5. What is the proper procedure for updating the checksum for a port distfile when the file changes without a version change?

When the checksum for a distribution file is updated due to the author updating the file without changing the port revision, the commit message includes a summary of the relevant diffs between the original and new distfile to ensure that the distfile has not been corrupted or maliciously altered. If the current version of the port has been in the ports tree for a while, a copy of the old distfile will usually be available on the ftp servers; otherwise the author or maintainer should be contacted to find out why the distfile has changed.

22.8.6. How can an experimental test build of the ports tree (exp-run) be requested?

An exp-run must be completed before patches with a significant ports impact are committed. The patch can be against the ports tree or the base system.

Full package builds will be done with the patches provided by the submitter, and the submitter is required to fix detected problems (fallout) before commit.