Index: user/jgh/committers-guide/Makefile =================================================================== --- user/jgh/committers-guide/Makefile (nonexistent) +++ user/jgh/committers-guide/Makefile (revision 296065) @@ -0,0 +1,23 @@ +# +# $FreeBSD$ +# +# Article: The FreeBSD Committers Guide + +DOC?= article + +FORMATS?= html +WITH_ARTICLE_TOC?= YES + +INSTALL_COMPRESSED?= gz +INSTALL_ONLY_COMPRESSED?= + +SRCS= article.xml + +IMAGES_LIB= callouts/1.png +IMAGES_LIB+= callouts/2.png +IMAGES_LIB+= callouts/3.png + +URL_RELPREFIX?= ../../../.. +DOC_PREFIX?= ${.CURDIR}/../../.. + +.include "${DOC_PREFIX}/share/mk/doc.project.mk" Property changes on: user/jgh/committers-guide/Makefile ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/jgh/committers-guide/article.xml =================================================================== --- user/jgh/committers-guide/article.xml (nonexistent) +++ user/jgh/committers-guide/article.xml (revision 296065) @@ -0,0 +1,5043 @@ + + +]> + +
+ + + Committer's Guide + + + The &os; Documentation Project + + + + 1999 + 2000 + 2001 + 2002 + 2003 + 2004 + 2005 + 2006 + 2007 + 2008 + 2009 + 2010 + 2011 + 2012 + 2013 + 2014 + 2015 + The &os; Documentation Project + + + + &tm-attrib.freebsd; + &tm-attrib.coverity; + &tm-attrib.ibm; + &tm-attrib.intel; + &tm-attrib.sparc; + &tm-attrib.general; + + + $FreeBSD$ + + $FreeBSD$ + + + This document provides information for the &os; + committer community. All new committers should read this + document before they start, and existing committers are + strongly encouraged to review it from time to time. + + Almost all &os; developers have commit rights to one or + more repositories. However, a few developers do not, and some + of the information here applies to them as well. (For + instance, some people only have rights to work with the + Problem Report database). Please see + for more information. + + This document may also be of interest to members of the + &os; community who want to learn more about how the project + works. + + + + + Administrative Details + + + + + + + + Login Methods + &man.ssh.1;, protocol 2 only + + + + Main Shell Host + freefall.FreeBSD.org + + + + src/ Subversion + Root + svn+ssh://repo.FreeBSD.org/base + (see also ). + + + + doc/ Subversion + Root + svn+ssh://repo.FreeBSD.org/doc + (see also ). + + + + ports/ Subversion + Root + + svn+ssh://repo.FreeBSD.org/ports + (see also ). + + + + Internal Mailing Lists + developers (technically called all-developers), + doc-developers, doc-committers, ports-developers, + ports-committers, src-developers, src-committers. (Each + project repository has its own -developers and + -committers mailing lists. Archives for these lists can + be found in the files + /local/mail/repository-name-developers-archive + and + /local/mail/repository-name-committers-archive + on the FreeBSD.org + cluster.) + + + + + Core Team monthly + reports + /home/core/public/monthly-reports + on the FreeBSD.org + cluster. + + + + Ports Management Team monthly + reports + /home/portmgr/public/monthly-reports + on the FreeBSD.org + cluster. + + + + Noteworthy src/ SVN + Branches + + stable/8 (8.X-STABLE), + stable/9 (9.X-STABLE), + stable/10 (10.X-STABLE), + head (-CURRENT) + + + + + + &man.ssh.1; is required to connect to the project hosts. + For more information, see . + + Useful links: + + + + &os; + Project Internal Pages + + + + &os; + Project Hosts + + + + &os; + Project Administrative Groups + + + + + + Open<acronym>PGP</acronym> Keys for &os; + + Cryptographic keys conforming to the + OpenPGP (Pretty Good + Privacy) standard are used by the &os; project to + authenticate committers. Messages carrying important + information like public SSH keys can be + signed with the OpenPGP key to prove that + they are really from the committer. See + PGP & + GPG: Email for the Practical Paranoid by Michael Lucas + and + for more information. + + + Creating a Key + + Existing keys can be used, but should be checked with + doc/head/share/pgpkeys/checkkey.sh + first. + + For those who do not yet have an + OpenPGP key, or need a new key to meet &os; + security requirements, here we show how to generate + one. + + + + + Install + security/gnupg. Enter + these lines in ~/.gnupg/gpg.conf to + set minimum acceptable defaults: + + fixed-list-mode +keyid-format 0xlong +personal-digest-preferences SHA512 SHA384 SHA256 SHA224 +default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 BZIP2 ZLIB ZIP Uncompressed +use-agent +verify-options show-uid-validity +list-options show-uid-validity +sig-notation issuer-fpr@notations.openpgp.fifthhorseman.net=%g +cert-digest-algo SHA512 + + + + Generate a key: + + &prompt.user; 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 +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 +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 +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. + + + + 2048-bit keys with a three-year expiration provide + adequate protection at present (2013-12). + describes the situation in more detail. + + + + A three year key lifespan is short enough to + obsolete keys weakened by advancing computer power, + but long enough to reduce key management + problems. + + + + Use your real name here, preferably matching that + shown on government-issued ID to + make it easier for others to verify your identity. + Text that may help others identify you can be entered + in the Comment section. + + + + After the email address is entered, a passphrase is + requested. Methods of creating a secure passphrase are + contentious. Rather than suggest a single way, here are + some links to sites that describe various methods: , + , + , + . + + + + Protect your private key and passphrase. If either the + private key or passphrase may have been compromised or + disclosed, immediately notify + accounts@FreeBSD.org and revoke the key. + + Committing the new key is shown in + . + + + + + Kerberos and LDAP web Password for &os; Cluster + + The &os; cluster requires a Kerberos password to access + certain services. The Kerberos password also serves as the + LDAP web password, since LDAP is proxying to Kerberos in the + cluster. Some of the services + which require this include: + + + + Bugzilla + + + Jenkins + + + + To create a new Kerberos account in the &os; cluster, or to + reset a Kerberos password for an existing account using a random + password generator: + + &prompt.user; ssh kpasswd.freebsd.org + + + This must be done from a machine outside of the &os;.org + cluster. + + + A Kerberos password can also be set manually + by logging into freefall.FreeBSD.org and + running: + + &prompt.user; kpasswd + + + Unless you have used the Kerberos-authenticated services + of the &os;.org cluster previously, + Client unknown will be shown. This + error means that the + ssh kpasswd.freebsd.org method shown above + must be used first to initialize your Kerberos account. + + + + + + Commit Bit Types + + The &os; repository has a number of components which, when + combined, support the basic operating system source, + documentation, third party application ports infrastructure, and + various maintained utilities. When &os; commit bits are + allocated, the areas of the tree where the bit may be used are + specified. Generally, the areas associated with a bit reflect + who authorized the allocation of the commit bit. Additional + areas of authority may be added at a later date: when this + occurs, the committer should follow normal commit bit allocation + procedures for that area of the tree, seeking approval from the + appropriate entity and possibly getting a mentor for that area + for some period of time. + + + + + + Committer Type + Responsible + Tree Components + + + + src + core@ + src/, doc/ subject to appropriate review + + + + doc + doceng@ + doc/, ports/, src/ documentation + + + + ports + portmgr@ + ports/ + + + + + + Commit bits allocated prior to the development of the notion + of areas of authority may be appropriate for use in many parts + of the tree. However, common sense dictates that a committer + who has not previously worked in an area of the tree seek review + prior to committing, seek approval from the appropriate + responsible party, and/or work with a mentor. Since the rules + regarding code maintenance differ by area of the tree, this is + as much for the benefit of the committer working in an area of + less familiarity as it is for others working on the tree. + + Committers are encouraged to seek review for their work as + part of the normal development process, regardless of the area + of the tree where the work is occurring. + + + Policy for Committer Activity in Other Trees + + + + All committers may modify + base/head/share/misc/committers-*.dot, + base/head/usr.bin/calendar/calendars/calendar.freebsd, + and + ports/head/astro/xearth/files. + + + + doc committers may commit + documentation changes to src + files, such as man 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. + + + + Committers can aquire 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. + + + + "Approved by" is only acceptable from non-mentored src + committers -- mentored committers can provide a "Reviewed + by" but not an "Approved by". + + + + + + + Subversion Primer + + It is assumed that you are already familiar with the basic + operation of Subversion. If not, start by reading the + Subversion + Book. + + + Introduction + + The &os; source repository switched from + CVS to Subversion on May 31st, 2008. The + first real SVN commit is + r179447. + + The &os; doc/www repository switched + from CVS to Subversion on May 19th, 2012. + The first real SVN commit is + r38821. + + The &os; ports repository switched + from CVS to Subversion on July 14th, 2012. + The first real SVN commit is + r300894. + + Subversion can be installed from the &os; Ports + Collection by issuing these commands: + + &prompt.root; pkg install subversion + + + + + Getting Started + + There are a few ways to obtain a working copy of the tree + from Subversion. This section will explain them. + + + Direct Checkout + + The first is to check out directly from the main + repository. For the src tree, + use: + + &prompt.user; svn checkout svn+ssh://repo.freebsd.org/base/head /usr/src + + For the doc tree, use: + + &prompt.user; svn checkout svn+ssh://repo.freebsd.org/doc/head /usr/doc + + For the ports tree, use: + + &prompt.user; svn checkout svn+ssh://repo.freebsd.org/ports/head /usr/ports + + + Though the remaining examples in this document are + written with the workflow of working with the + src tree in mind, the underlying + concepts are the same for working with the + doc and the ports + tree. + Ports related Subversion operations are listed in + . + + + The above command will check out a + CURRENT source tree as + /usr/src/, + which can be any target directory on the local filesystem. + Omitting the final argument of that command causes the + working copy, in this case, to be named head, + but that can be renamed safely. + + svn+ssh means the + SVN protocol tunnelled over + SSH. The name of the server is + repo.freebsd.org, base + is the path to the repository, and head + is the subdirectory within the repository. + + If your &os; login name is different from your login + name on your local machine, you must either include it in + the URL (for example + svn+ssh://jarjar@repo.freebsd.org/base/head), + or add an entry to your ~/.ssh/config + in the form: + + Host repo.freebsd.org + User jarjar + + This is the simplest method, but it is hard to tell just + yet how much load it will place on the repository. + + + The svn diff does not require + access to the server as SVN stores a + reference copy of every file in the working copy. This, + however, means that Subversion working copies are very + large in size. + + + + + Checkout from a Mirror + + Check out a working copy from a mirror by + substituting the mirror's URL for + svn+ssh://repo.freebsd.org/base. This + can be an official mirror or a mirror maintained by using + svnsync. + + There is a serious disadvantage to this method: every + time something is to be committed, a + svn relocate to the master repository has + to be done, remembering to svn relocate + back to the mirror after the commit. Also, since + svn relocate only works between + repositories that have the same UUID, some hacking of the + local repository's UUID has to occur before it is possible + to start using it. + + The hassle of a local + svnsync mirror probably is not worth it + unless the network connectivity situation or other factors + demand it. If it is needed, see the end of this chapter for + information on how to set one up. + + + + <literal>RELENG_*</literal> Branches and General + Layout + + In svn+ssh://repo.freebsd.org/base, + base refers to the source tree. + Similarly, ports refers to the ports + tree, and so on. These are separate repositories with their + own change number sequences, access controls and commit + mail. + + For the base repository, HEAD refers to the -CURRENT + tree. For example, head/bin/ls is what + would go into /usr/src/bin/ls in a + release. Some key locations are: + + + + /head/ which corresponds to + HEAD, also known as + -CURRENT. + + + + /stable/n + which corresponds to + RELENG_n. + + + + /releng/n.n + which corresponds to + RELENG_n_n. + + + + /release/n.n.n + which corresponds to + RELENG_n_n_n_RELEASE. + + + + /vendor* is the vendor branch + import work area. This directory itself does not + contain branches, however its subdirectories do. This + contrasts with the stable, + releng and + release directories. + + + + /projects and + /user feature a branch work area, + like in Perforce. As above, the + /user directory does not contain + branches itself. + + + + + + &os; Documentation Project Branches and + Layout + + In svn+ssh://repo.freebsd.org/doc, + doc refers to the repository root of + the source tree. + + In general, most &os; Documentation Project work will be + done within the head/ branch of the + documentation source tree. + + &os; documentation is written and/or translated to + various languages, each in a separate + directory in the head/ + branch. + + Each translation set contains several subdirectories for + the various parts of the &os; Documentation Project. A few + noteworthy directories are: + + + + /articles/ contains the source + code for articles written by various &os; + contributors. + + + + /books/ contains the source + code for the different books, such as the + &os; Handbook. + + + + /htdocs/ contains the source + code for the &os; website. + + + + + + &os; Ports Tree Branches and Layout + + In svn+ssh://repo.freebsd.org/ports, + ports refers to the repository root of + the ports tree. + + In general, most &os; port work will be done within the + head/ branch of the ports tree which is + the actual ports tree used to install software. Some other + key locations are: + + + + /branches/RELENG_n_n_n + which corresponds to + RELENG_n_n_n + is used to merge back security updates in preparation + for a release. + + + + /tags/RELEASE_n_n_n + which corresponds to + RELEASE_n_n_n + represents a release tag of the ports tree. + + + + /tags/RELEASE_n_EOL + represents the end of life tag of a specific &os; + branch. + + + + + + + Daily Use + + This section will explain how to perform common day-to-day + operations with Subversion. + + + Help + + SVN has built in help documentation. + It can be accessed by typing the following command: + + &prompt.user; svn help + + Additional information can be found in the + Subversion + Book. + + + + Checkout + + As seen earlier, to check out the &os; head + branch: + + &prompt.user; svn checkout svn+ssh://repo.freebsd.org/base/head /usr/src + + At some point, more than just HEAD + will probably be useful, for instance when merging changes + to stable/7. Therefore, it may be useful to have a partial + checkout of the complete tree (a full checkout would be very + painful). + + To do this, first check out the root of the + repository: + + &prompt.user; svn checkout --depth=immediates svn+ssh://repo.freebsd.org/base + + This will give base with all the + files it contains (at the time of writing, just + ROADMAP.txt) and empty subdirectories + for head, stable, + vendor and so on. + + Expanding the working copy is possible. Just change the + depth of the various subdirectories: + + &prompt.user; svn up --set-depth=infinity base/head +&prompt.user; svn up --set-depth=immediates base/release base/releng base/stable + + The above command will pull down a full copy of + head, plus empty copies of every + release tag, every + releng branch, and every + stable branch. + + If at a later date merging to + 7-STABLE is required, expand the working + copy: + + &prompt.user; svn up --set-depth=infinity base/stable/7 + + Subtrees do not have to be expanded completely. For + instance, expanding only stable/7/sys and + then later expand the rest of + stable/7: + + &prompt.user; svn up --set-depth=infinity base/stable/7/sys +&prompt.user; svn up --set-depth=infinity base/stable/7 + + Updating the tree with svn update + will only update what was previously asked for (in this + case, head and + stable/7; it will not pull down the whole + tree. + + + Decreasing the depth of a working copy is not + possible. + + + + + Anonymous Checkout + + It is possible to anonymously check out the &os; + repository with Subversion. This will give access to a + read-only tree that can be updated, but not committed back + to the main repository. To do this, use the following + command: + + &prompt.user; svn co https://svn.FreeBSD.org/base/head /usr/src + + More details on using Subversion this way can be found + in Using + Subversion. + + + + Updating the Tree + + To update a working copy to either the latest revision, + or a specific revision: + + &prompt.user; svn update +&prompt.user; svn update -r12345 + + + + Status + + To view the local changes that have been made to the + working copy: + + &prompt.user; svn status + + To show local changes and files that are out-of-date + do: + + &prompt.user; svn status --show-updates + + + + Editing and Committing + + Unlike Perforce, SVN does not need to + be told in advance about file editing. + + To commit all changes in + the current directory and all subdirectories: + + &prompt.user; svn commit + + To commit all changes in, for example, + lib/libfetch/ + and + usr/bin/fetch/ + in a single operation: + + &prompt.user; svn commit lib/libfetch usr/bin/fetch + + There is also a commit wrapper for the ports tree to + handle the properties and sanity checking your + changes: + + &prompt.user; /usr/ports/Tools/scripts/psvn commit + + + + Adding and Removing Files + + + Before adding files, get a copy of auto-props.txt + (there is also a + ports tree specific version) and add it to + ~/.subversion/config according to the + instructions in the file. If you added something before + reading this, use svn rm --keep-local + for just added files, fix your config file and re-add them + again. The initial config file is created when you first + run a svn command, even something as simple as + svn help. + + + Files are added to a + SVN repository with svn + add. To add a file named + foo, edit it, then: + + &prompt.user; svn add foo + + + Most new source files should include a + $&os;$ string near the + start of the file. On commit, svn will + expand the $&os;$ string, + adding the file path, revision number, date and time of + commit, and the username of the committer. Files which + cannot be modified may be committed without the + $&os;$ string. + + + Files can be removed with svn + remove: + + &prompt.user; svn remove foo + + Subversion does not require deleting the file before + using svn rm, and indeed complains if + that happens. + + It is possible to add directories with + svn add: + + &prompt.user; mkdir bar +&prompt.user; svn add bar + + Although svn mkdir makes this easier + by combining the creation of the directory and the adding of + it: + + &prompt.user; svn mkdir bar + + Like files, directories are removed with + svn rm. There is no separate command + specifically for removing directories. + + &prompt.user; svn rm bar + + + + Copying and Moving Files + + This command creates a copy of + foo.c named bar.c, + with the new file also under version control: + + &prompt.user; svn copy foo.c bar.c + + The example above is equivalent to: + + &prompt.user; cp foo.c bar.c +&prompt.user; svn add bar.c + + To move and rename a file: + + &prompt.user; svn move foo.c bar.c + + + + Log and Annotate + + svn log shows revisions and commit + messages, most recent first, for files or directories. When + used on a directory, all revisions that affected the + directory and files within that directory are shown. + + svn annotate, or equally svn + praise or svn blame, shows + the most recent revision number and who committed that + revision for each line of a file. + + + + Diffs + + svn diff displays changes to the + working copy. Diffs generated by SVN are + unified and include new files by default in the diff + output. + + svn diff can show the changes between + two revisions of the same file: + + &prompt.user; svn diff -r179453:179454 ROADMAP.txt + + It can also show all changes for a specific changeset. + The following will show what changes were made to the + current directory and all subdirectories in changeset + 179454: + + &prompt.user; svn diff -c179454 . + + + + Reverting + + Local changes (including additions and deletions) can be + reverted using svn revert. It does not + update out-of-date files, but just replaces them with + pristine copies of the original version. + + + + Conflicts + + If an svn update resulted in a merge + conflict, Subversion will remember which files have + conflicts and refuse to commit any changes to those files + until explicitly told that the conflicts have been resolved. + The simple, not yet deprecated procedure is the + following: + + &prompt.user; svn resolved foo + + However, the preferred procedure is: + + &prompt.user; svn resolve --accept=working foo + + The two examples are equivalent. Possible values for + --accept are: + + + + working: use the version in your + working directory (which one presumes has been edited to + resolve the conflicts). + + + + base: use a pristine copy of the + version you had before svn update, + discarding your own changes, the conflicting changes, + and possibly other intervening changes as well. + + + + mine-full: use what you had + before svn update, including your own + changes, but discarding the conflicting changes, and + possibly other intervening changes as well. + + + + theirs-full: use the version that + was retrieved when you did + svn update, discarding your own + changes. + + + + + + + Advanced Use + + + Sparse Checkouts + + SVN allows + sparse, or partial checkouts of a + directory by adding to a + svn checkout. + + Valid arguments to + are: + + + + empty: the directory itself + without any of its contents. + + + + files: the directory and any + files it contains. + + + + immediates: the directory and any + files and directories it contains, but none of the + subdirectories' contents. + + + + infinity: anything. + + + + The --depth option applies to many + other commands, including svn commit, + svn revert, and svn + diff. + + Since --depth is sticky, there is a + --set-depth option for svn + update that will change the selected depth. + Thus, given the working copy produced by the previous + example: + + &prompt.user; cd ~/freebsd +&prompt.user; svn update --set-depth=immediates . + + The above command will populate the working copy in + ~/freebsd with + ROADMAP.txt and empty subdirectories, + and nothing will happen when svn update + is executed on the subdirectories. However, the following + command will set the depth for + head (in this case) to infinity, + and fully populate it: + + &prompt.user; svn update --set-depth=infinity head + + + + Direct Operation + + Certain operations can be performed directly on the + repository without touching the working copy. Specifically, + this applies to any operation that does not require editing + a file, including: + + + + log, + diff + + + + mkdir + + + + remove, copy, + rename + + + + propset, + propedit, + propdel + + + + merge + + + + Branching is very fast. The following command would be + used to branch RELENG_8: + + &prompt.user; svn copy svn+ssh://repo.freebsd.org/base/head svn+ssh://repo.freebsd.org/base/stable/8 + + This is equivalent to the following set of commands + which take minutes and hours as opposed to seconds, + depending on your network connection: + + &prompt.user; svn checkout --depth=immediates svn+ssh://repo.freebsd.org/base +&prompt.user; cd base +&prompt.user; svn update --set-depth=infinity head +&prompt.user; svn copy head stable/8 +&prompt.user; svn commit stable/8 + + + + Merging with <acronym>SVN</acronym> + + This section deals with merging code from one branch to + another (typically, from head to a stable branch). + + + In all examples below, $FSVN + refers to the location of the &os; Subversion repository, + svn+ssh://repo.freebsd.org/base/. + + + + About Merge Tracking + + From the user's perspective, merge tracking + information (or mergeinfo) is stored in a property called + svn:mergeinfo, which is a + comma-separated list of revisions and ranges of revisions + that have been merged. When set on a file, it applies + only to that file. When set on a directory, it applies to + that directory and its descendants (files and directories) + except for those that have their own + svn:mergeinfo. + + It is not inherited. For + instance, stable/6/contrib/openpam/ + does not implicitly inherit mergeinfo from + stable/6/, or + stable/6/contrib/. + Doing so would make partial checkouts very hard to manage. + Instead, mergeinfo is explicitly propagated down the tree. + For merging something into + branch/foo/bar/, + the following rules apply: + + + + If + branch/foo/bar/ + does not already have a mergeinfo record, but a direct + ancestor (for instance, + branch/foo/) + does, then that record will be propagated down to + branch/foo/bar/ + before information about the current merge is + recorded. + + + + Information about the current merge will + not be propagated back up that + ancestor. + + + + If a direct descendant of + branch/foo/bar/ (for instance, + branch/foo/bar/baz/) already has + a mergeinfo record, information about the current + merge will be propagated down to it. + + + + If you consider the case where a revision changes + several separate parts of the tree (for example, + branch/foo/bar/ and + branch/foo/quux/), but you only want + to merge some of it (for example, + branch/foo/bar/), you will see that + these rules make sense. If mergeinfo was propagated up, + it would seem like that revision had also been merged to + branch/foo/quux/, when in fact it had + not been. + + + + Selecting the Source and Target for + <literal>stable/10</literal> and Newer + + Starting with the stable/10 + branch, all merges should be + merged to and committed from the root of the + branch. All merges should look like: + + &prompt.user; svn merge -c r123456 ^/head/ checkout +&prompt.user; svn commit checkout + + Note that checkout should + be a complete checkout of the branch to which the merge + occurs. + + Merges to releng/ branches should + always originate from the corresponding + stable/ branch. For example: + + &prompt.user; svn merge -c r123456 ^/stable/10 releng/10.0 + + + + Selecting the Source and Target for + <literal>stable/9</literal> and Older + + For stable/9 and earlier, + a different strategy was used, distributing mergeinfo + around the tree so that merges could be performed without + a complete checkout. This procedure proved extremely + error-prone, with the convenience of partial checkouts for + merges significantly outweighed by the complexity of + picking mergeinfo targets. The below describes this + now-obsoleted procedure, which should be used + only for merges prior to + stable/10. + + Because of mergeinfo propagation, it is important to + choose the source and target for the merge carefully to + minimise property changes on unrelated directories. + + The rules for selecting the merge target (the + directory that you will merge the changes to) can be + summarized as follows: + + + + Never merge directly to a file. + + + + Never, ever merge directly to a file. + + + + Never, ever, ever merge + directly to a file. + + + + Changes to kernel code should be merged to + sys/. For instance, a change to + the &man.ichwd.4; driver should be merged to + sys/, not + sys/dev/ichwd/. Likewise, a + change to the TCP/IP stack should be merged to + sys/, not + sys/netinet/. + + + + Changes to code under etc/ + should be merged at etc/, not + below it. + + + + Changes to vendor code (code in + contrib/, + crypto/ and so on) should be + merged to the directory where vendor imports happen. + For instance, a change to + crypto/openssl/util/ should be + merged to crypto/openssl/. This + is rarely an issue, however, since changes to vendor + code are usually merged wholesale. + + + + Changes to userland programs should as a general + rule be merged to the directory that contains the + Makefile for that program. For instance, a change to + usr.bin/xlint/arch/i386/ should + be merged to + usr.bin/xlint/. + + + + Changes to userland libraries should as a general + rule be merged to the directory that contains the + Makefile for that library. For instance, a change to + lib/libc/gen/ should be merged to + lib/libc/. + + + + There may be cases where it makes sense to deviate + from the rules for userland programs and libraries. + For instance, everything under + lib/libpam/ is merged to + lib/libpam/, even though the + library itself and all of the modules each have their + own Makefile. + + + + Changes to manual pages should be merged to + share/man/manN/, + for the appropriate value of + N. + + + + Other changes to share/ + should be merged to the appropriate subdirectory and + not to share/ directly. + + + + Changes to a top-level file in the source tree + such as UPDATING or + Makefile.inc1 should be merged + directly to that file rather than to the root of the + whole tree. Yes, this is an exception to the first + three rules. + + + + When in doubt, ask. + + + + If you need to merge changes to several places at once + (for instance, changing a kernel interface and every + userland program that uses it), merge each target + separately, then commit them together. For instance, if + you merge a revision that changed a kernel + API and updated all the userland bits + that used that API, you would merge the + kernel change to sys, and the userland bits to the + appropriate userland directories, then commit all of these + in one go. + + The source will almost invariably be the same as the + target. For instance, you will always merge + stable/7/lib/libc/ from + head/lib/libc/. The only exception + would be when merging changes to code that has moved in + the source branch but not in the parent branch. For + instance, a change to &man.pkill.1; would be merged from + bin/pkill/ in head to + usr.bin/pkill/ in stable/7. + + + + Preparing the Merge Target + + Because of the mergeinfo propagation issues described + earlier, it is very important that you never merge changes + into a sparse working copy. You must always have a full + checkout of the branch you will merge into. For instance, + when merging from HEAD to 7, you must have a full checkout + of stable/7: + + &prompt.user; cd stable/7 +&prompt.user; svn up --set-depth=infinity + + The target directory must also be up-to-date and must + not contain any uncommitted changes or stray files. + + + + Identifying Revisions + + Identifying revisions to be merged is a must. If the + target already has complete mergeinfo, ask + SVN for a list: + + &prompt.user; cd stable/6/contrib/openpam +&prompt.user; svn mergeinfo --show-revs=eligible $FSVN/head/contrib/openpam + + If the target does not have complete mergeinfo, check + the log for the merge source. + + + + Merging + + Now, let us start merging! + + + The Principles + + Say you would like to merge: + + + + revision $R + + + + in directory $target in stable branch + $B + + + + from directory $source in head + + + + $FSVN is + svn+ssh://repo.freebsd.org/base + + + + Assuming that revisions $P and $Q have + already been merged, and that the current directory is + an up-to-date working copy of stable/$B, the + existing mergeinfo looks like this: + + &prompt.user; svn propget svn:mergeinfo -R $target +$target - /head/$source:$P,$Q + + Merging is done like so: + + &prompt.user; svn merge -c$R $FSVN/head/$source $target + + Checking the results of this is possible with + svn diff. + + The svn:mergeinfo now looks like: + + &prompt.user; svn propget svn:mergeinfo -R $target +$target - head/$source:$P,$Q,$R + + If the results are not exactly as shown, assistance + may be required before committing as mistakes may have + been made, or there may be something wrong with the + existing mergeinfo, or there may be a bug in + Subversion. + + + + Practical Example + + As a practical example, consider the following + scenario. The changes to netmap.4 + in r238987 are to be merged from CURRENT to 9-STABLE. + The file resides in + head/share/man/man4. According + to , this is + also where to do the merge. Note that in this example + all paths are relative to the top of the svn repository. + For more information on the directory layout, see . + + The first step is to inspect the existing + mergeinfo. + + &prompt.user; svn propget svn:mergeinfo -R stable/9/share/man/man4 + + Take a quick note of how it looks before moving on + to the next step; doing the actual merge: + + &prompt.user; svn merge -c r238987 svn+ssh://repo.freebsd.org/base/head/share/man/man4 stable/9/share/man/man4 +--- Merging r238987 into 'stable/9/share/man/man4': +U stable/9/share/man/man4/netmap.4 +--- Recording mergeinfo for merge of r238987 into +'stable/9/share/man/man4': + U stable/9/share/man/man4 + + Check that the revision number of the merged + revision has been added. Once this is verified, the + only thing left is the actual commit. + + &prompt.user; svn commit stable/9/share/man/man4 + + + + Merging into the Kernel + (<filename>sys/</filename>) + + As stated above, merging into the kernel is + different from merging in the rest of the tree. In many + ways merging to the kernel is simpler because there is + always the same merge target + (sys/). + + Once svn merge has been executed, + svn diff has to be run on the + directory to check the changes. This may show some + unrelated property changes, but these can be ignored. + Next, build and test the kernel, and, once the tests are + complete, commit the code as normal, making sure that + the commit message starts with Merge + r226222 from head, + or similar. + + + + + Precautions Before Committing + + As always, build world (or appropriate parts of + it). + + Check the changes with svn diff and + svn stat. Make sure all the files that + should have been added or deleted were in fact added or + deleted. + + Take a closer look at any property change (marked by a + M in the second column of svn + stat). Normally, no svn:mergeinfo properties + should be anywhere except the target directory (or + directories). + + If something looks fishy, ask for help. + + + + Committing + + Make sure to commit a top level directory to have the + mergeinfo included as well. Do not specify individual + files on the command line. For more information about + committing files in general, see the relevant section of + this primer. + + + + + Vendor Imports with <acronym>SVN</acronym> + + + Please read this entire section before starting a + vendor import. + + + + Patches to vendor code fall into two + categories: + + + + Vendor patches: these are patches that have been + issued by the vendor, or that have been extracted from + the vendor's version control system, which address + issues which in your opinion cannot wait until the + next vendor release. + + + + &os; patches: these are patches that modify the + vendor code to address &os;-specific issues. + + + + The nature of a patch dictates where it should be + committed: + + + + Vendor patches should be committed to the vendor + branch, and merged from there to head. If the patch + addresses an issue in a new release that is currently + being imported, it must not be + committed along with the new release: the release must + be imported and tagged first, then the patch can be + applied and committed. There is no need to re-tag the + vendor sources after committing the patch. + + + + &os; patches should be committed directly to + head. + + + + + + Preparing the Tree + + If importing for the first time after the switch to + Subversion, flattening and cleaning up the vendor tree is + necessary, as well as bootstrapping the merge history in + the main tree. + + + Flattening + + During the conversion from CVS to + Subversion, vendor branches were imported with the same + layout as the main tree. This means that the + pf vendor sources ended up in + vendor/pf/dist/contrib/pf. The + vendor source is best directly in + vendor/pf/dist. + + To flatten the pf tree: + + &prompt.user; cd vendor/pf/dist/contrib/pf +&prompt.user; svn mv $(svn list) ../.. +&prompt.user; cd ../.. +&prompt.user; svn rm contrib +&prompt.user; svn propdel -R svn:mergeinfo . +&prompt.user; svn commit + + The propdel bit is necessary + because starting with 1.5, Subversion will automatically + add svn:mergeinfo to any directory + that is copied or moved. In this case, as nothing is + being merged from the deleted tree, they just get in the + way. + + Tags may be flattened as well (3, 4, 3.5 etc.); the + procedure is exactly the same, only changing + dist to 3.5 or + similar, and putting the svn commit + off until the end of the process. + + + + Cleaning Up + + The dist tree can be cleaned up + as necessary. Disabling keyword expansion is + recommended, as it makes no sense on unmodified vendor + code and in some cases it can even be harmful. + OpenSSH, for example, + includes two files that originated with &os; and still + contain the original version tags. To do this: + + &prompt.user; svn propdel svn:keywords -R . +&prompt.user; svn commit + + + + Bootstrapping Merge History + + If importing for the first time after the switch to + Subversion, bootstrap svn:mergeinfo + on the target directory in the main tree to the revision + that corresponds to the last related change to the + vendor tree, prior to importing new sources: + + &prompt.user; cd head/contrib/pf +&prompt.user; svn merge --record-only svn+ssh://repo.freebsd.org/base/vendor/pf/dist@180876 . +&prompt.user; svn commit + + + + + Importing New Sources + + With two commits—one for the import itself and + one for the tag—this step can optionally be repeated + for every upstream release between the last import and the + current import. + + + Preparing the Vendor Sources + + Unlike in CVS where only the + needed parts were imported into the vendor tree to avoid + bloating the main tree, Subversion is able to store a + full distribution in the vendor tree. So, import + everything, but merge only what is required. + + A svn add is required to add any + files that were added since the last vendor import, and + svn rm is required to remove any that + were removed since. Preparing sorted lists of the + contents of the vendor tree and of the sources that are + about to be imported is recommended, to facilitate the + process. + + &prompt.user; cd vendor/pf/dist +&prompt.user; svn list -R | grep -v '/$' | sort >../old +&prompt.user; cd ../pf-4.3 +&prompt.user; find . -type f | cut -c 3- | sort >../new + + With these two files, + comm -23 ../old ../new will list + removed files (files only in old), + while comm -13 ../old ../new will + list added files only in + new. + + + + Importing into the Vendor Tree + + Now, the sources must be copied into + dist and + the svn add and + svn rm commands should be used as + needed: + + &prompt.user; cd vendor/pf/pf-4.3 +&prompt.user; tar cf - . | tar xf - -C ../dist +&prompt.user; cd ../dist +&prompt.user; comm -23 ../old ../new | xargs svn rm +&prompt.user; comm -13 ../old ../new | xargs svn --parents add + + If any directories were removed, they will have to + be svn rmed manually. Nothing will + break if they are not, but they will remain in the + tree. + + Check properties on any new files. All text files + should have svn:eol-style set to + native. All binary files should have + svn:mime-type set to + application/octet-stream unless there + is a more appropriate media type. Executable files + should have svn:executable set to + *. No other properties should exist + on any file in the tree. + + Committing is now possible, however it is good + practice to make sure that everything is OK by using the + svn stat and + svn diff commands. + + + + Tagging + + Once committed, vendor releases should be tagged for + future reference. The best and quickest way to do this + is directly in the repository: + + &prompt.user; svn cp svn+ssh://repo.freebsd.org/base/vendor/pf/dist svn+ssh://repo.freebsd.org/base/vendor/pf/4.3 + + Once that is complete, svn up the + working copy of + vendor/pf + to get the new tag, although this is rarely + needed. + + If creating the tag in the working copy of the tree, + svn:mergeinfo results must be + removed: + + &prompt.user; cd vendor/pf +&prompt.user; svn cp dist 4.3 +&prompt.user; svn propdel svn:mergeinfo -R 4.3 + + + + + Merging to Head + + &prompt.user; cd head/contrib/pf +&prompt.user; svn up +&prompt.user; svn merge --accept=postpone svn+ssh://repo.freebsd.org/base/vendor/pf/dist . + + The --accept=postpone tells + Subversion that it should not complain because merge + conflicts will be taken care of manually. + + + The cvs2svn changeover occurred + on June 3, 2008. When performing vendor merges for + packages which were already present and converted by the + cvs2svn process, the command used to + merge + /vendor/package_name/dist + to + /head/package_location + (for example, + head/contrib/sendmail) must use + to + indicate the revision to merge from the + /vendor tree. For example: + + &prompt.user; svn checkout svn+ssh://repo.freebsd.org/base/head/contrib/sendmail +&prompt.user; cd sendmail +&prompt.user; svn merge -c r261190 ^/vendor/sendmail/dist . + + ^ is an alias for the + repository path. + + + + If using the Zsh shell, + the ^ must be escaped with + \. This means + ^/head should be + \^/head. + + + It is necessary to resolve any merge conflicts. + + Make sure that any files that were added or removed in + the vendor tree have been properly added or removed in the + main tree. To check diffs against the vendor + branch: + + &prompt.user; svn diff --no-diff-deleted --old=svn+ssh://repo.freebsd.org/base/vendor/pf/dist --new=. + + The --no-diff-deleted tells + Subversion not to complain about files that are in the + vendor tree but not in the main tree, i.e., things that + would have previously been removed before the vendor + import, like for example the vendor's makefiles + and configure scripts. + + Using CVS, once a file was off the + vendor branch, it was not able to be put back. With + Subversion, there is no concept of on or off the vendor + branch. If a file that previously had local + modifications, to make it not show up in diffs in the + vendor tree, all that has to be done is remove any + left-over cruft like &os; version tags, which is much + easier. + + If any changes are required for the world to build + with the new sources, make them now, and keep testing + until everything builds and runs perfectly. + + + + Committing the Vendor Import + + Committing is now possible! Everything must be + committed in one go. If done properly, the tree will move + from a consistent state with old code, to a consistent + state with new code. + + + + From Scratch + + + Importing into the Vendor Tree + + This section is an example of importing and tagging + byacc into + head. + + First, prepare the directory in + vendor: + + &prompt.user; svn co --depth immediates $FSVN/vendor +&prompt.user; cd vendor +&prompt.user; svn mkdir byacc +&prompt.user; svn mkdir byacc/dist + + Now, import the sources into the + dist directory. + Once the files are in place, svn add + the new ones, then svn commit and tag + the imported version. To save time and bandwidth, + direct remote committing and tagging is possible: + + &prompt.user; svn cp -m "Tag byacc 20120115" $FSVN/vendor/byacc/dist $FSVN/vendor/byacc/20120115 + + + + Merging to <literal>head</literal> + + Due to this being a new file, copy it for the + merge: + + &prompt.user; svn cp -m "Import byacc to contrib" $FSVN/vendor/byacc/dist $FSVN/head/contrib/byacc + + Working normally on newly imported sources is still + possible. + + + + + + Reverting a Commit + + Reverting a commit to a previous version is fairly + easy: + + &prompt.user; svn merge -r179454:179453 ROADMAP.txt +&prompt.user; svn commit + + Change number syntax, with negative meaning a reverse + change, can also be used: + + &prompt.user; svn merge -c -179454 ROADMAP.txt +&prompt.user; svn commit + + This can also be done directly in the repository: + + &prompt.user; svn merge -r179454:179453 svn+ssh://repo.freebsd.org/base/ROADMAP.txt + + + It is important to ensure that the mergeinfo + is correct when reverting a file in order to permit + svn mergeinfo --eligible to work as + expected. + + + Reverting the deletion of a file is slightly different. + Copying the version of the file that predates the deletion + is required. For example, to restore a file that was + deleted in revision N, restore version N-1: + + &prompt.user; svn copy svn+ssh://repo.freebsd.org/base/ROADMAP.txt@179454 +&prompt.user; svn commit + + or, equally: + + &prompt.user; svn copy svn+ssh://repo.freebsd.org/base/ROADMAP.txt@179454 svn+ssh://repo.freebsd.org/base + + Do not simply recreate the file + manually and svn add it—this will + cause history to be lost. + + + + Fixing Mistakes + + While we can do surgery in an emergency, do not plan on + having mistakes fixed behind the scenes. Plan on mistakes + remaining in the logs forever. Be sure to check the output + of svn status and svn + diff before committing. + + Mistakes will happen but, + they can generally be fixed without + disruption. + + Take a case of adding a file in the wrong location. The + right thing to do is to svn move the file + to the correct location and commit. This causes just a + couple of lines of metadata in the repository journal, and + the logs are all linked up correctly. + + The wrong thing to do is to delete the file and then + svn add an independent copy in the + correct location. Instead of a couple of lines of text, the + repository journal grows an entire new copy of the file. + This is a waste. + + + + Setting up a <application>svnsync</application> + Mirror + + You probably do not want to do this unless there is a + good reason for it. Such reasons might be to support many + multiple local read-only client machines, or if your network + bandwidth is limited. Starting a fresh mirror from empty + would take a very long time. Expect a minimum of 10 hours + for high speed connectivity. If you have international + links, expect this to take 4 to 10 times longer. + + A far better option is to grab a seed file. It is large + (~1GB) but will consume less network traffic and take less + time to fetch than a svnsync will. This is possible in one + of the following three ways: + + &prompt.user; rsync -va --partial --progress freefall:/home/peter/svnmirror-base-r179637.tbz2 . + + &prompt.user; rsync -va --partial --progress rsync://repoman.freebsd.org:50873/svnseed/svnmirror-base-r215629.tar.xz . + + &prompt.user; fetch ftp://ftp.freebsd.org/pub/FreeBSD/development/subversion/svnmirror-base-r221445.tar.xz + + Once you have the file, extract it to somewhere like + home/svnmirror/base/. + Then, update it, so that it fetches changes since the last + revision in the archive: + + &prompt.user; svnsync sync file:///home/svnmirror/base + + You can then set that up to run from &man.cron.8;, do + checkouts locally, set up a svnserve server for your local + machines to talk to, etc. + + The seed mirror is set to fetch from + svn://svn.freebsd.org/base. The + configuration for the mirror is stored in + revprop 0 on the local mirror. To see + the configuration, try: + + &prompt.user; svn proplist -v --revprop -r 0 file:///home/svnmirror/base + + Use propset to change things. + + + + Committing High-<acronym>ASCII</acronym> Data + + Files that have high-ASCII bits are + considered binary files in SVN, so the + pre-commit checks fail and indicate that the + mime-type property should be set to + application/octet-stream. However, the + use of this is discouraged, so please do not set it. The + best way is always avoiding high-ASCII + data, so that it can be read everywhere with any text editor + but if it is not avoidable, instead of changing the + mime-type, set the fbsd:notbinary + property with propset: + + &prompt.user; svn propset fbsd:notbinary yes foo.data + + + + Maintaining a Project Branch + + A project branch is one that is synced to head (or + another branch) is used to develop a project then commit it + back to head. In SVN, + dolphin branching is used for this. A + dolphin branch is one that diverges for a + while and is finally committed back to the original branch. + During development code migration in one direction (from + head to the branch only). No code is committed back to head + until the end. Once you commit back at the end, the branch + is dead (although you can have a new branch with the same + name after you delete the branch if you want). + + As per http://people.freebsd.org/~peter/svn_notes.txt, + work that is intended to be merged back into HEAD should be + in base/projects/. If you are doing + work that is beneficial to the &os; community in some way + but not intended to be merged directly back into HEAD then + the proper location is + base/user/your-name/. + This + page contains further details. + + To create a project branch: + + &prompt.user; svn copy svn+ssh://repo.freebsd.org/base/head svn+ssh://repo.freebsd.org/base/projects/spif + + To merge changes from HEAD back into the project + branch: + + &prompt.user; cd copy_of_spif +&prompt.user; svn merge svn+ssh://repo.freebsd.org/base/head +&prompt.user; svn commit + + It is important to resolve any merge conflicts before + committing. + + + + + + Some Tips + + In commit logs etc., rev 179872 should be + spelled r179872 as per convention. + + Speeding up svn is possible by adding the following to + ~/.ssh/config: + + Host * +ControlPath ~/.ssh/sockets/master-%l-%r@%h:%p +ControlMaster auto +ControlPersist yes + + and then typing + + mkdir ~/.ssh/sockets + + Checking out a working copy with a stock Subversion client + without &os;-specific patches + (OPTIONS_SET=FREEBSD_TEMPLATE) will mean + that $FreeBSD$ tags will not + be expanded. Once the correct version has been installed, + trick Subversion into expanding them like so: + + &prompt.user; svn propdel -R svn:keywords . +&prompt.user; svn revert -R . + + This will wipe out uncommitted patches. + + It is possible to automatically fill the "Sponsored by" + and "MFC after" commit log fields by setting + "freebsd-sponsored-by" and "freebsd-mfc-after" fields in the + "[miscellany]" section of the + ~/.subversion/config configuration file. + For example: + + freebsd-sponsored-by = The FreeBSD Foundation +freebsd-mfc-after = 2 weeks + + + + + Setup, Conventions, and Traditions + + There are a number of things to do as a new developer. + The first set of steps is specific to committers only. These + steps must be done by a mentor for those who are not + committers. + + + For New Committers + + Those who have been given commit rights to the &os; + repositories must follow these steps. + + + + Get mentor approval before committing each of these + changes! + + + + The .ent and + .xml files mentioned below exist in + the &os; Documentation Project SVN repository at svn.FreeBSD.org/doc/. + + + + New files that do not have the + FreeBSD=%H + svn:keywords property will be rejected + when attempting to commit them to the repository. Be sure + to read + + regarding adding and removing files. Verify that + ~/.subversion/config contains the + necessary auto-props entries from + auto-props.txt mentioned + there. + + + + All src commits should go to + &os.current; first before being merged to &os.stable;. + The &os.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 + + + Add an Author Entity + + doc/head/share/xml/authors.ent + — Add an author entity. Later steps depend on this + entity, and missing this step will cause the + doc/ build to fail. This is a + relatively easy task, but remains a good first test of + version control skills. + + + + Update the List of Developers and + Contributors + + doc/head/en_US.ISO8859-1/articles/contributors/contrib.committers.xml + — + Add an entry to the Developers section + of the Contributors + List. Entries are sorted by last name. + + doc/head/en_US.ISO8859-1/articles/contributors/contrib.additional.xml + — Remove the entry from the + Additional Contributors section. Entries + are sorted by first name. + + + + Add a News Item + + doc/head/share/xml/news.xml + — Add an entry. Look for the other entries that + announce new committers and follow the format. Use the + date from the commit bit approval email from + core@FreeBSD.org. + + + + Add a <acronym>PGP</acronym> Key + + doc/head/share/pgpkeys/pgpkeys.ent + and + doc/head/share/pgpkeys/pgpkeys-developers.xml + - Add your PGP or + GnuPG key. Those who do not yet have a + key should see . + + &a.des.email; has written a shell script + (doc/head/share/pgpkeys/addkey.sh) to + make this easier. See the README + file for more information. + + Use + doc/head/share/pgpkeys/checkkey.sh to + verify that keys meet minimal best-practices + standards. + + After adding and checking a key, add both updated + files to source control and then commit them. Entries in + this file are sorted by last name. + + + It is very important to have a current + PGP/GnuPG key in + the repository. The key may be required for positive + identification of a committer. For example, the + &a.admins; might need it for account recovery. A + complete keyring of FreeBSD.org users is + available for download from http://www.FreeBSD.org/doc/pgpkeyring.txt. + + + + + Update Mentor and Mentee Information + + base/head/share/misc/committers-repository.dot + — Add an entry to the current committers section, + where repository is + doc, ports, or + src, depending on the commit privileges + granted. + + Add an entry for each additional mentor/mentee + relationship in the bottom section. + + + + Generate a <application>Kerberos</application> + Password + + See to generate or + set a Kerberos for use with + other &os; services like the bug tracking database. + + + + Optional: Enable Wiki Account + + &os; + Wiki Account — A wiki account allows + sharing projects and ideas. Those who do not yet have an + account can contact clusteradm@FreeBSD.org + to obtain one. + + + + Optional: Update Wiki Information + + Wiki Information - After gaining access to the wiki, + some people add entries to the How We + Got Here, + Irc + Nicks, and Dogs + of FreeBSD pages. + + + + Optional: Update Ports with Personal + Information + + ports/astro/xearth/files/freebsd.committers.markers + and + src/usr.bin/calendar/calendars/calendar.freebsd + - Some people add entries for themselves to these files to + show where they are located or the date of their + birthday. + + + + Optional: Prevent Duplicate Mailings + + Subscribers to &a.svn-src-all.name;, + &a.svn-ports-all.name; or &a.svn-doc-all.name; might wish + to unsubscribe to avoid receiving duplicate copies of + commit messages and followups. + + + + + + For Everyone + + + + 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 + &os;, and who will be your mentor. Email this to the + &a.developers; and you will be on your way! + + + + 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 &a.committers; and + the &a.developers;. 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 read it and you will not lose it. + + 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. If you want these + checks turned off for your email you can place a file + named .spam_lover in your home + directory on freefall.FreeBSD.org + to disable the checks for your email. + + + + + 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. + + + + + Mentors + + All new developers have a mentor assigned to them for + the first few months. A mentor is responsible for teaching + the mentee the rules and conventions of the project and + guiding their first steps in the developer community. The + mentor is also personally responsible for the mentee's actions + during this initial period. + + For committers: do not commit anything without first + getting mentor approval. Document that approval with an + Approved by: line in the commit + message. + + When the mentor decides that a mentee has learned the + ropes and is ready to commit on their own, the mentor + announces it with a commit to + mentors. + + + + + Commit Log Messages + + This section contains some suggestions and traditions for + how commit logs are formatted. + + As well as including an informative message with each + commit you may need to include some additional + information. + + This information consists of one or more lines + containing the key word or phrase, a colon, tabs for formatting, + and then the additional information. + + The key words or phrases are: + + + + + + PR: + The problem report (if any) which is affected + (typically, by being closed) by this commit. Only + include one PR per line as the automated scripts which + parse this line cannot understand more than + one. + + + + Differential Revision: + The full URL of the Phabricator review. For + example: + https://reviews.freebsd.org/D1708. + + + + Submitted by: + + The name and e-mail address of the person + that submitted the fix; for developers, just the + username on the &os; cluster. + + If the submitter is the maintainer of the port + to which you are committing, include "(maintainer)" + after the email address. + + Avoid obfuscating the email address of the + submitter as this adds additional work when searching + logs. + + + + + Reviewed by: + The name and e-mail address of the person or + people that reviewed the change; for developers, + just the username on the &os; cluster. If a + patch was submitted to a mailing list for review, + and the review was favorable, then just include + the list name. + + + + Approved by: + The name and e-mail address of the person or + people that approved the change; for developers, just + the username on the &os; cluster. It is customary to + get prior approval for a commit if it is to an area of + the tree to which you do not usually commit. In + addition, during the run up to a new release all commits + must be approved by the release + engineering team. + + While under mentorship, get mentor approval before + the commit. Enter the mentor's username in this field, + and note that they are a mentor: + + Approved by: username-of-mentor (mentor) + + If a team approved these commits then include the + team name followed by the username of the approver in + parentheses. For example: + + Approved by: re (username) + + + + Obtained from: + The name of the project (if any) from which + the code was obtained. Do not use this line for the + name of an individual person. + + + + MFC after: + If you wish to receive an e-mail reminder to + MFC at a later date, specify the + number of days, weeks, or months after which an + MFC is planned. + + + + Relnotes: + If the change is a candidate for inclusion in + the release notes for the next release from the branch, + set to yes. + + + + Security: + If the change is related to a security + vulnerability or security exposure, include one or more + references or a description of the issue. If possible, + include a VuXML URL or a CVE ID. + + + + + + + Commit Log for a Commit Based on a PR + + You want to commit a change based on a PR submitted by + John Smith containing a patch. The end of the commit message + should look something like this. + + ... + + PR: 12345 + Submitted by: John Smith <John.Smith@example.com> + + + + Commit Log for a Commit Needing Review + + You want to change the virtual memory system. You have + posted patches to the appropriate mailing list (in this + case, freebsd-arch) and the changes have + been approved. + + ... + + Reviewed by: -arch + + + + Commit Log for a Commit Needing Approval + + You want to commit a port. You have collaborated with + the listed MAINTAINER, who has told you to go ahead and + commit. + + ... + + Approved by: abc (maintainer) + + Where abc is the account name + of the person who approved. + + + + Commit Log for a Commit Bringing in Code from + OpenBSD + + You want to commit some code based on work done in the + OpenBSD project. + + ... + + Obtained from: OpenBSD + + + + Commit Log for a Change to &os.current; with a Planned + Commit to &os.stable; to Follow at a Later Date. + + You want to commit some code which will be merged from + &os.current; into the &os.stable; branch after two + weeks. + + ... + +MFC after: 2 weeks + + Where 2 is the number of days, + weeks, or months after which an MFC is + planned. The weeks option may be + day, days, + week, weeks, + month, months. + + + In many cases you may need to combine some of these. + + Consider the situation where a user has submitted a PR + containing code from the NetBSD project. You are looking at the + PR, but it is not an area of the tree you normally work in, so + you have decided to get the change reviewed by the + arch mailing list. Since the change is + complex, you opt to MFC after one month to + allow adequate testing. + + The extra information to include in the commit would look + something like + + + Example Combined Commit Log + + PR: 54321 +Submitted by: John Smith <John.Smith@example.com> +Reviewed by: -arch +Obtained from: NetBSD +MFC after: 1 month +Relnotes: yes + + + + + Preferred License for New Files + + Currently the &os; Project suggests and uses the following + text as the preferred license scheme: + + /*- + * Copyright (c) [year] [your name] + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND + * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE + * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL + * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS + * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY + * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + * SUCH DAMAGE. + * + * [id for your version control system, if any] + */ + + The &os; project strongly discourages the so-called + "advertising clause" in new code. Due to the large number of + contributors to the &os; project, complying with this clause for + many commercial vendors has become difficult. If you have code + in the tree with the advertising clause, please consider + removing it. In fact, please consider using the above license + for your code. + + The &os; project discourages completely new licenses and + variations on the standard licenses. New licenses require the + approval of the &a.core; to reside in the + main repository. The more different licenses that are used in + the tree, the more problems that this causes to those wishing to + utilize this code, typically from unintended consequences from a + poorly worded license. + + Project policy dictates that code under some non-BSD + licenses must be placed only in specific sections of the + repository, and in some cases, compilation must be conditional + or even disabled by default. For example, the GENERIC kernel + must be compiled under only licenses identical to or + substantially similar to the BSD license. GPL, APSL, CDDL, etc, + licensed software must not be compiled into GENERIC. + + Developers are reminded that in open source, getting "open" + right is just as important as getting "source" right, as + improper handling of intellectual property has serious + consequences. Any questions or concerns should immediately be + brought to the attention of the core team. + + + + Keeping Track of Licenses Granted to the &os; + Project + + Various software or data exist in the repositories where + the &os; project has been granted a special licence to be able + to use them. A case in point are the Terminus fonts for use + with &man.vt.4;. Here the author Dimitar Zhekov has allowed us + to use the "Terminus BSD Console" font under a 2-clause BSD + license rather than the regular Open Font License he normally + uses. + + It is clearly sensible to keep a record of any such + license grants. To that end, the &a.core; has decided to keep + an archive of them. Whenever the &os; project is granted a + special license we require the &a.core; to be notified. Any + developers involved in arranging such a license grant, please + send details to the &a.core; including: + + + + Contact details for people or organizations granting the + special license. + + + + What files, directories etc. in the repositories are + covered by the license grant including the revision numbers + where any specially licensed material was committed. + + + + The date the license comes into effect from. Unless + otherwise agreed, this will be the date the license was + issued by the authors of the software in question. + + + + The license text. + + + + A note of any restrictions, limitations or exceptions + that apply specifically to &os;'s usage of the licensed + material. + + + + Any other relevant information. + + + + Once the &a.core; is satisfied that all the necessary + details have been gathered and are correct, the secretary will + send a PGP-signed acknowledgement of receipt including the + license details. This receipt will be persistently archived and + serve as our permanent record of the license grant. + + The license archive should contain only details of license + grants; this is not the place for any discussions around + licensing or other subjects. Access to data within the license + archive will be available on request to the &a.core;. + + + + Developer Relations + + If you are working directly on your own code or on code + which is already well established as your responsibility, then + there is probably little need to check with other committers + before jumping in with a commit. If you see a bug in an area of + the system which is clearly orphaned (and there are a few such + areas, to our shame), the same applies. If, however, you are + about to modify something which is clearly being actively + maintained by someone else (and it is only by watching the + repository-committers + mailing list that you can really get a feel for just what is and + is not) then consider sending the change to them instead, just + as you would have before becoming a committer. For ports, you + should contact the listed MAINTAINER in the + Makefile. For other parts of the + repository, if you are unsure who the active maintainer might + be, it may help to scan the revision history to see who has + committed changes in the past. An example script that lists + each person who has committed to + a given file along with the number of commits each person has + made can be found at on freefall at + ~eadler/bin/whodid. If your queries go + unanswered or the committer otherwise indicates a lack of + interest in the area affected, go ahead and commit it. + + + Avoid sending private emails to maintainers. Other people + might be interested in the conversation, not just the final + output. + + + If you are unsure about a commit for any reason at all, have + it reviewed by -hackers before committing. + Better to have it flamed then and there rather than when it is + part of the repository. If you do happen to commit something + which results in controversy erupting, you may also wish to + consider backing the change out again until the matter is + settled. Remember – with a version control system we can + always change it back. + + Do not impugn the intentions of someone you disagree with. + If they see a different solution to a problem than you, or even + a different problem, it is not because they are stupid, because + they have questionable parentage, or because they are trying to + destroy your hard work, personal image, or &os;, but simply + because they have a different outlook on the world. Different + is good. + + Disagree honestly. Argue your position from its merits, + be honest about any shortcomings it may have, and be open to + seeing their solution, or even their vision of the problem, + with an open mind. + + Accept correction. We are all fallible. When you have made + a mistake, apologize and get on with life. Do not beat up + yourself, and certainly do not beat up others for your mistake. + Do not waste time on embarrassment or recrimination, just fix + the problem and move on. + + Ask for help. Seek out (and give) peer reviews. One of + the ways open source software is supposed to excel is in the + number of eyeballs applied to it; this does not apply if nobody + will review code. + + + + If in Doubt... + + When you are not sure about something, whether it be a + technical issue or a project convention be sure to ask. If you + stay silent you will never make progress. + + If it relates to a technical issue ask on the public + mailing lists. Avoid the temptation to email the individual + person that knows the answer. This way everyone will be able to + learn from the question and the answer. + + For project specific or administrative questions you should + ask, in order: + + + + Your mentor or former mentor. + + + + An experienced committer on IRC, email, etc. + + + + Any team with a "hat", as they should give you a + definitive answer. + + + + If still not sure, ask on &a.developers;. + + + + Once your question is answered, if no one pointed you to + documentation that spelled out the answer to your question, + document it, as others will have the same question. + + + + Bugzilla + + The &os; Project utilizes + Bugzilla for tracking bugs and change + requests. Be sure that if you commit a fix or suggestion found + in the PR database to close it. It is also considered nice if + you take time to close any PRs associated with your commits, if + appropriate. + + Committers with + non-&os;.org + Bugzilla accounts can have the old account merged with the + &os;.org account by + entering a new bug. Choose + Supporting Services as the Product, and + Bug Tracker as the Component. + + You can find out more about + Bugzilla at: + + + + &os; + Problem Report Handling Guidelines + + + + http://www.FreeBSD.org/support.html + + + + + + Phabricator + + The &os; Project utilizes Phabricator + for code review requests. See the CodeReview + wiki page for details. + + + + + Who's Who + + Besides the repository meisters, there are other &os; + project members and teams whom you will probably get to know in + your role as a committer. Briefly, and by no means + all-inclusively, these are: + + + + &a.doceng; + + + doceng is the group responsible for the documentation + build infrastructure, approving new documentation + committers, and ensuring that the &os; website and + documentation on the FTP site is up to date with respect + to the subversion tree. It is + not a conflict resolution body. + The vast majority of documentation related discussion + takes place on the &a.doc;. More details regarding the + doceng team can be found in its charter. + Committers interested in contributing to the documentation + should familiarize themselves with the Documentation + Project Primer. + + + + + &a.bde.email; + + + Bruce is the Style Police-Meister. When you do a + commit that could have been done better, Bruce will be + there to tell you. Be thankful that someone is. Bruce is + also very knowledgeable on the various standards + applicable to &os;. + + + + + &a.re.members.email; + + + These are the members of the &a.re;. This team is + responsible for setting release deadlines and controlling + the release process. During code freezes, the release + engineers have final authority on all changes to the + system for whichever branch is pending release status. If + there is something you want merged from &os.current; to + &os.stable; (whatever values those may have at any given + time), these are the people to talk to about it. + + Hiroki is also the keeper of the release documentation + (src/release/doc/*). If you commit a + change that you think is worthy of mention in the release + notes, please make sure he knows about it. Better still, + send him a patch with your suggested commentary. + + + + + &a.so.email; + + + &a.so; is the + &os; Security + Officer and oversees the + &a.security-officer;. + + + + + &a.wollman.email; + + + If you need advice on obscure network internals or + are not sure of some potential change to the networking + subsystem you have in mind, Garrett is someone to talk + to. Garrett is also very knowledgeable on the various + standards applicable to &os;. + + + + + &a.committers; + + + &a.svn-src-all.name;, &a.svn-ports-all.name; and + &a.svn-doc-all.name; are the mailing lists that the + version control system uses to send commit messages to. + You should never send email directly + to these lists. You should only send replies to this list + when they are short and are directly related to a + commit. + + + + + &a.developers; + + + All committers are subscribed to -developers. This + list was created to be a forum for the committers + community issues. Examples are Core + voting, announcements, etc. + + The &a.developers; is for the exclusive use of &os; + committers. In order to develop &os;, committers must + have the ability to openly discuss matters that will be + resolved before they are publicly announced. Frank + discussions of work in progress are not suitable for open + publication and may harm &os;. + + All &os; committers are expected not to + not publish or forward messages from the + &a.developers; outside the list membership without + permission of all of the authors. Violators will be + removed from the + &a.developers;, resulting in a suspension of commit + privileges. Repeated or flagrant violations may result in + permanent revocation of commit privileges. + + This list is not intended as a + place for code reviews or for any technical discussion. + In fact using it as such hurts the &os; Project as it + gives a sense of a closed list where general decisions + affecting all of the &os; using community are made without + being open. Last, but not least + never, never ever, email the &a.developers; and + CC:/BCC: another &os; list. Never, ever email + another &os; email list and CC:/BCC: the &a.developers;. + Doing so can greatly diminish the benefits of this + list. + + + + + + + SSH Quick-Start Guide + + + + If you do not wish to type your password in every time + you use &man.ssh.1;, and you use RSA or DSA keys to + authenticate, &man.ssh-agent.1; is there for your + convenience. If you want to use &man.ssh-agent.1;, make + sure that you run it before running other applications. X + users, for example, usually do this from their + .xsession or + .xinitrc. See &man.ssh-agent.1; for + details. + + + + Generate a key pair using &man.ssh-keygen.1;. The key + pair will wind up in your + $HOME/.ssh/ + directory. + + + + Send your public key + ($HOME/.ssh/id_dsa.pub + or + $HOME/.ssh/id_rsa.pub) + to the person setting you up as a committer so it can be put + into + yourlogin + in + /etc/ssh-keys/ on + freefall. + + + + Now you should be able to use &man.ssh-add.1; for + authentication once per session. This will prompt you for + your private key's pass phrase, and then store it in your + authentication agent (&man.ssh-agent.1;). If you no longer + wish to have your key stored in the agent, issuing + ssh-add -d will remove it. + + Test by doing something such as ssh + freefall.FreeBSD.org ls /usr. + + For more information, see + security/openssh, + &man.ssh.1;, &man.ssh-add.1;, &man.ssh-agent.1;, + &man.ssh-keygen.1;, and &man.scp.1;. + + For information on adding, changing, or removing &man.ssh.1; + keys, see this + article. + + + + &coverity; Availability for &os; Committers + + All &os; developers can obtain access to + Coverity analysis results of all &os; + Project software. All who are interested in obtaining access to + the analysis results of the automated + Coverity runs, can sign up at Coverity + Scan. + + The &os; wiki includes a mini-guide for developers who are + interested in working with the &coverity; analysis reports: http://wiki.freebsd.org/CoverityPrevent. + Please note that this mini-guide is only readable by &os; + developers, so if you cannot access this page, you will have to + ask someone to add you to the appropriate Wiki access + list. + + Finally, all &os; developers who are going to use + &coverity; are always encouraged to ask for more details and + usage information, by posting any questions to the mailing list + of the &os; developers. + + + + The &os; Committers' Big List of Rules + + Everyone involved with the &os; project is expected to + abide by the Code of Conduct available from + http://www.FreeBSD.org/internal/code-of-conduct.html. + As committers, you form the public face of the project, and how + you behave has a vital impact on the public perception of it. + This guide expands on the parts of the + Code of Conduct specific to + committers. + + + + Respect other committers. + + + + Respect other contributors. + + + + Discuss any significant change + before committing. + + + + Respect existing maintainers (if listed in the + MAINTAINER field in + Makefile or in + MAINTAINER in the top-level + directory). + + + + 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. + + + + Changes go to &os.current; before &os.stable; unless + specifically permitted by the release engineer or unless + they are not applicable to &os.current;. Any non-trivial or + non-urgent change which is applicable should also be allowed + to sit in &os.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 &os.stable; branch + as outlined for the maintainer in rule #5. + + + + Do not fight in public with other committers; it looks + bad. + + + + Respect all code freezes and read the + committers and + developers mailing lists in a timely + manner so you know when a code freeze is in effect. + + + + When in doubt on any procedure, ask first! + + + + Test your changes before committing them. + + + + Do not commit to anything under the + src/contrib, + src/crypto, or + src/sys/contrib trees without + explicit approval from the respective + maintainer(s). + + + + As noted, breaking some of these rules can be grounds for + suspension or, upon repeated offense, permanent removal of + commit privileges. Individual members of core have the power to + temporarily suspend commit privileges until core as a whole has + the chance to review the issue. In case of an + emergency (a committer doing damage to the + repository), a temporary suspension may also be done by the + repository meisters. Only a 2/3 majority of core has the + authority to suspend commit privileges for longer than a week or + to remove them permanently. This rule does not exist to set + core up as a bunch of cruel dictators who can dispose of + committers as casually as empty soda cans, but to give the + project a kind of safety fuse. If someone is out of control, it + is important to be able to deal with this immediately rather + than be paralyzed by debate. In all cases, a committer whose + privileges are suspended or revoked is entitled to a + hearing by core, the total duration of the + suspension being determined at that time. A committer whose + privileges are suspended may also request a review of the + decision after 30 days and every 30 days thereafter (unless the + total suspension period is less than 30 days). A committer + whose privileges have been revoked entirely may request a review + after a period of 6 months has elapsed. This review policy is + strictly informal and, in all cases, core + reserves the right to either act on or disregard requests for + review if they feel their original decision to be the right + one. + + In all other aspects of project operation, core is a subset + of committers and is bound by the + same rules. Just because someone is in + core this does not mean that they have special dispensation to + step outside any of the lines painted here; core's + special powers only kick in when it acts as a + group, not on an individual basis. As individuals, the core + team members are all committers first and core second. + + + Details + + + + 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 person(s) 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. + + + + 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. + + Consider the points raised under + and apply them also to + contributors. + + + + Discuss any significant change + before committing. + + The repository is not where changes should be + initially submitted for correctness or argued over, that + should happen first in the mailing lists or by use of the + Phabricator service and the commit should only happen once + something resembling consensus has been reached. This + does not mean that you have to ask permission before + correcting every obvious syntax error or manual page + misspelling, simply that you should try 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 you are on the right + track is to have your code reviewed by one or more other + committers. + + When in doubt, ask for review! + + + + Respect existing maintainers if listed. + + Many parts of &os; 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 http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/policies.html + 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, + you can also look at the repository logs for the file(s) + in question and see if someone has been working recently + or predominantly in that area. + + Other areas of &os; fall under the control of someone + who manages an overall category of &os; evolution, such as + internationalization or networking. See http://www.FreeBSD.org/administration.html + for more information on this. + + + + 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. + + + + Changes go to &os.current; before &os.stable; unless + specifically permitted by the release engineer or unless + they are not applicable to &os.current;. Any non-trivial + or non-urgent change which is applicable should also be + allowed to sit in &os.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 + &os.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 &os.stable; + branch. The management of &os.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 &os.stable; and different rules apply + there than in &os.current;. There is also really no point + in having &os.current; be a testing ground if changes are + merged over to &os.stable; immediately. Changes need a + chance to be tested by the &os.current; developers, so + allow some time to elapse before merging unless the + &os.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 &a.security-officer;, or in some cases, by a + member of the &a.re;. + + + + 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. That means that you should not air your + angry words in public and you should 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 you 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. + + + + 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 &os; Happy Reeducation Camp we + run in Greenland. + + + + 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. + + + + Test your changes before committing them. + + + This may sound obvious, but if it really were so + obvious then we probably would not see so many cases of + people clearly not doing this. 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 refer to the + &os; + Internal Page for a list of available resources. + As other architectures are added to the &os; supported + platforms list, the appropriate shared testing resources + will be made available. + + + + Do not commit to anything under the + src/contrib, + src/crypto, and + src/sys/contrib trees without + explicit approval from the respective + maintainer(s). + + The trees mentioned above are for contributed software + usually imported onto a vendor branch. Committing + something there, even if it does not take the file off the + vendor branch, may cause unnecessary headaches for those + responsible for maintaining that particular piece of + software. Thus, unless you have + explicit approval from the maintainer + (or you are the maintainer), do not + commit there! + + Please note that this does not mean you should not try + to improve the software in question; you are still more + than welcome to do so. Ideally, you should submit your + patches to the vendor. If your changes are + &os;-specific, talk to the maintainer; they may be + willing to apply them locally. But whatever you do, do + not commit there by yourself! + + Contact the &a.core; if you wish to take up + maintainership of an unmaintained part of the tree. + + + + + + Policy on Multiple Architectures + + &os; has added several new architecture ports during + recent release cycles and is truly no longer an &i386; centric + operating system. In an effort to make it easier to keep + &os; portable across the platforms we support, core has + developed the following mandate: + +
+ Our 32-bit reference platform is &arch.i386;, and our + 64-bit reference platform is &arch.sparc64;. Major design + work (including major API and ABI changes) must prove + itself on at least one 32-bit and at least one 64-bit + platform, preferably the primary reference platforms, + before it may be committed to the source tree. +
+ + The &arch.i386; and &arch.sparc64; platforms were chosen + due to being more readily available to developers and as + representatives of more diverse processor and system designs - + big versus little endian, register file versus register stack, + different DMA and cache implementations, hardware page tables + versus software TLB management etc. + + The &arch.ia64; platform has many of the same + complications that &arch.sparc64; has, but is still limited in + availability to developers. + + We will continue to re-evaluate this policy as cost and + availability of the 64-bit platforms change. + + Developers should also be aware of our Tier Policy for + the long term support of hardware architectures. The rules + here are intended to provide guidance during the development + process, and are distinct from the requirements for features + and architectures listed in that section. The Tier rules for + feature support on architectures at release-time are more + strict than the rules for changes during the development + process. + + + + Other Suggestions + + When committing documentation changes, use a spell checker + before committing. For all XML docs, verify that the + formatting directives are correct by running + make lint and + textproc/igor. + + For manual pages, run sysutils/manck + and textproc/igor + over the manual page to verify all of the cross + references and file references are correct and that the man + page has all of the appropriate MLINKs + installed. + + Do not mix style fixes with new functionality. A style + fix is any change which does not modify the functionality of + the code. Mixing the changes obfuscates the functionality + change when asking for differences between revisions, which + can hide any new bugs. Do not include whitespace changes with + content changes in commits to doc/ . + The extra clutter in the diffs + makes the translators' job much more difficult. Instead, make + any style or whitespace changes in separate commits that are + clearly labeled as such in the commit message. + + + + Deprecating Features + + When it is necessary to remove functionality from software + in the base system the following guidelines should be followed + whenever possible: + + + + 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. + + + + The option, utility, or interface is preserved until + the next major (point zero) release. + + + + 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. + + + + + + Privacy and Confidentiality + + + + Most &os; business is done in public. + + &os; 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. + + + + Certain sensitive matters must remain private or + held under embargo. + + There unfortunately cannot be complete transparency. + As a &os; 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. + + + + The Security Officer has sole control over the + release of security advisories. + + Where there are security problems that affect many + different operating systems, &os; frequently depends on + early access in order to be able to prepare advisories for + coordinated release. Unless &os; 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 + in order to prepare security fixes. + + + + 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. + + + + 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. + + + + Private communications should 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. + + + + Communications on project-only or restricted access + channels should be treated as private. + + Similarly to personal communications, certain + internal communications channels, including &os; Committer + only mailing lists and restricted access IRC channels + should be considered as private communications. You need + permission in order to publish material from these + sources. + + + + 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. + + + + + + + Support for Multiple Architectures + + &os; is a highly portable operating system intended to + function on many different types of hardware architectures. + Maintaining clean separation of Machine Dependent (MD) and + Machine Independent (MI) code, as well as minimizing MD code, is + an important part of our strategy to remain agile with regards + to current hardware trends. Each new hardware architecture + supported by &os; adds substantially to the cost of code + maintenance, toolchain support, and release engineering. It + also dramatically increases the cost of effective testing of + kernel changes. As such, there is strong motivation to + differentiate between classes of support for various + architectures while remaining strong in a few key architectures + that are seen as the &os; target audience. + + + Statement of General Intent + + The &os; Project targets "production quality commercial + off-the-shelf (COTS) workstation, server, and high-end + embedded systems". By retaining a focus on a narrow set of + architectures of interest in these environments, the &os; + Project is able to maintain high levels of quality, stability, + and performance, as well as minimize the load on various + support teams on the project, such as the ports team, + documentation team, security officer, and release engineering + teams. Diversity in hardware support broadens the options for + &os; consumers by offering new features and usage + opportunities (such as support for 64-bit CPUs, use in + embedded environments, etc.), but these benefits must always + be carefully considered in terms of the real-world maintenance + cost associated with additional platform support. + + The &os; Project differentiates platform targets into + four tiers. Each tier includes a specification of the + requirements for an architecture to be in that tier, + as well as specifying the obligations of developers with + regards to the platform. In addition, a policy is defined + regarding the circumstances required to change the tier + of an architecture. + + + + Tier 1: Fully Supported Architectures + + Tier 1 platforms are fully supported by the security + officer, release engineering, and toolchain maintenance staff. + New features added to the operating system must be fully + functional across all Tier 1 architectures for every release + (features which are inherently architecture-specific, such as + support for hardware device drivers, may be exempt from this + requirement). In general, all Tier 1 platforms must have + build and Tinderbox support either in the FreeBSD.org cluster, + or be easily available for all developers. Embedded platforms + may substitute an emulator available in the &os; cluster + for actual hardware. + + Tier 1 architectures are expected to be Production Quality + with respects to all aspects of the &os; operating system, + including installation and development environments. + + Tier 1 architectures are expected to be completely + integrated into the source tree and have all features + necessary to produce an entire system relevant for that target + architecture. Tier 1 architectures generally have at least 6 + active developers. + + Tier 1 architectures are expected to be fully supported by + the ports system. All the ports should build on a Tier 1 + platform, or have the appropriate filters to prevent the + inappropriate ones from building there. The packaging system + must support all Tier 1 architectures. To ensure an + architecture's Tier 1 status, proponents of that architecture + must show that all relevant packages can be built on that + platform. + + Tier 1 embedded architectures must be able to cross-build + packages on at least one other Tier 1 architecture. The + packages must be the most relevant for the platform, but may + be a non-empty subset of those that build natively. + + Tier 1 architectures must be fully documented. All basic + operations need to be covered by the handbook or other + documents. All relevant integration documentation must also + be integrated into the tree, or readily available. + + Current Tier 1 platforms are &arch.i386; and + &arch.amd64;. + + + + Tier 2: Developmental Architectures + + Tier 2 platforms are not supported by the security officer + and release engineering teams. Platform maintainers are + responsible for toolchain support in the tree. The toolchain + maintainers are expected to work with the platform maintainers + to refine these changes. Major new toolchain components are + allowed to break support for Tier 2 architectures if the + &os;-local changes have not been incorporated upstream. + The toolchain maintainers are expected to provide prompt + review of any proposed changes and cannot block, through their + inaction, changes going into the tree. New features added to + &os; should be feasible to implement on these platforms, + but an implementation is not required before the feature may + be added to the &os; source tree. New features that may be + difficult to implement on Tier 2 architectures should provide + a means of disabling them on those architectures. The + implementation of a Tier 2 architecture may be committed to + the main &os; tree as long as it does not interfere with + production work on Tier 1 platforms, or substantially with + other Tier 2 platforms. Before a Tier 2 platform can be added + to the &os; base source tree, the platform must be able to + boot multi-user on actual hardware. Generally, there must be + at least three active developers working on the + platform. + + Tier 2 architectures are usually systems targeted at Tier + 1 support, but that are still under 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. + + Tier 2 architectures have basic support for them + integrated into the ports infrastructure. They may have cross + compilation support added, at the discretion of portmgr. Some + ports must built natively into packages if the package system + supports that architecture. If not integrated into the base + system, some external patches for the architecture for ports + must be available. + + Tier 2 architectures can be integrated into the &os; + handbook. The basics for how to get a system running must be + documented, although not necessarily for every single board or + system a Tier 2 architecture supports. The supported hardware + list must exist and should be relatively recent. It should be + integrated into the &os; documentation. + + Current Tier 2 platforms are &arch.arm;, &arch.arm64;, + &arch.ia64; (through &os; 10), + &arch.pc98;, &arch.powerpc;, and &arch.sparc64;. + + + + Tier 3: Experimental Architectures + + Tier 3 platforms are not supported by the security officer + and release engineering teams. At the discretion of the + toolchain maintainers, they may be supported in the toolchain. + 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 should be worked on + in external SCM repositories. + The transition to &os;'s subversion should take place after + the platform boots multi-user on hardware; sharing via + subversion is needed for wider exposure; and multiple + developers are actively working on the platform. + Platforms that transition to Tier 3 status may be + removed from the tree if they are no longer actively supported + by the &os; developer community at the discretion of the + release engineer. + + Tier 3 platforms may have ports support, either integrated + or external, but do not require it. + + Tier 3 platforms must have the basics documented for how + to build a kernel and how to boot it on at least one target + hardware or emulation environment. This documentation need + not be integrated into the &os; tree. + + Current Tier 3 platforms are &arch.mips;, and + &arch.riscv;. + + + + Tier 4: Unsupported Architectures + + Tier 4 systems are not supported in any form by the + project. + + All systems not otherwise classified into a support tier + are Tier 4 systems. The &arch.ia64; platform is transitioning + to Tier 4 status in &os; 11. + + + + Policy on Changing the Tier of an Architecture + + Systems may only be moved from one tier to another by + approval of the &os; Core Team, which shall make that + decision in collaboration with the Security Officer, Release + Engineering, and toolchain maintenance teams. + + + + + Ports Specific FAQ + + + + Adding a New Port + + + + How do I add a new port? + + + + First, please read the section about repository + copies. + + The easiest way to add a new port is the + addport script located in the + ports/Tools/scripts directory. It + adds a port from the directory specified, determining + the category automatically from the port + Makefile. It also adds an entry to + the port's category Makefile. It + was written by &a.mharo.email;, &a.will.email;, and + &a.garga.email;. When sending questions about this + script to the &a.ports;, please also CC &a.crees.email;, + the current maintainer. + + + + + + Any other things I need to know when I add a new + port? + + + + Check the port, preferably to make sure it compiles + and packages correctly. This is the recommended + sequence: + + &prompt.root; make install +&prompt.root; make package +&prompt.root; make deinstall +&prompt.root; pkg add package you built above +&prompt.root; make deinstall +&prompt.root; make reinstall +&prompt.root; make package + + The Porters + Handbook contains more detailed + instructions. + + Use &man.portlint.1; to check the syntax of the + port. 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 &os; + 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. + + + + + + Removing an Existing Port + + + + 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. + + + + Make sure there is no dependency on the port + in the ports collection: + + + + The port's PKGNAME should appear in exactly + one line in a recent INDEX file. + + + + No other ports should contain any reference + to the port's directory or PKGNAME in their + Makefiles + + + + + + Then, remove the port: + + + + Remove the port's files and directory with + svn remove. + + + + Remove the SUBDIR listing + of the port in the parent directory + Makefile. + + + + Add an entry to + ports/MOVED. + + + + Remove the port from + ports/LEGAL if it is + there. + + + + + + Alternatively, you can use the + rmport script, from + ports/Tools/scripts. This script + was written by &a.vd.email;. When sending questions + about this script to the &a.ports;, please also CC + &a.crees.email;, the current maintainer. + + + + + + Re-adding a Deleted Port + + + + How do I re-add a deleted port? + + + + This is essentially the reverse of deleting a + port. + + + Do not use svn add to add the + port. Follow these steps. If they are unclear, or + are not working, ask for help, do not just + svn add the port. + + + + + Figure out when the port was removed. Use this + list, + or look for the port on freshports, + and then copy the last living revision of the + port: + + &prompt.user; cd /usr/ports/category +&prompt.user; svn cp 'svn+ssh://repo.freebsd.org/ports/head/category/portname/@XXXXXX' portname + + Pick the revision that is just before the + removal. For example, if the revision where it was + removed is 269874, use + 269873. + + It is also possible to specify a date. In that + case, pick a date that is before the removal but + after the last commit to the port. + + &prompt.user; cd /usr/ports/category +&prompt.user; svn cp 'svn+ssh://repo.freebsd.org/ports/head/category/portname/@{YYYY-MM-DD}' portname + + + + Make the changes necessary to get the port + working again. If it was deleted because the + distfiles are no longer available, either + volunteer to host the distfiles, or find someone + else to do so. + + + + If some files have been added, or were removed + during the resurrection process, use svn + add or svn remove to + make sure all the files in the port will be + committed. + + + + Restore the SUBDIR listing of + the port in the parent directory + Makefile, keeping the entries + sorted. + + + + Delete the port entry from + ports/MOVED. + + + + If the port had an entry in + ports/LEGAL, restore it. + + + + svn commit these changes, + preferably in one step. + + + + + The addport script mentioned in + now detects when the + port to add has previously existed, and attempts to + handle all except the ports/LEGAL + step automatically. + + + + + + + Repository Copies + + + + When do we need a repository copy? + + + + When you want to add a port that is related to any + port that is already in the tree in a separate + directory, you have to do a repository copy. Here + related means it is a different + version or a slightly modified version. Examples are + print/ghostscript* (different + versions) and x11-wm/windowmaker* + (English-only and internationalized version). + + Another example is when a port is moved from one + subdirectory to another, or when you want to change the + name of a directory because the author(s) renamed their + software even though it is a descendant of a port + already in a tree. + + + + + + What do I need to do? + + + + With Subversion, a repo copy can be done by any + committer: + + + + Doing a repo copy: + + + + Verify that the target directory does + not exist. + + + + Use svn up to make + certain the original files, directories, and + checkout information is current. + + + + Use svn move or + svn copy to do the repo + copy. + + + + Upgrade the copied port to the new version. + Remember to add or change the + PKGNAMEPREFIX or + PKGNAMESUFFIX so there are no + duplicate ports with the same name. In some + rare cases it may be necessary to change the + PORTNAME instead of adding + PKGNAMEPREFIX or + PKGNAMESUFFIX, but this + should only be done when it is really needed + — e.g., using an existing port as the base + for a very similar program with a different + name, or upgrading a port to a new upstream + version which actually changes the distribution + name, like the transition from + textproc/libxml to + textproc/libxml2. In most + cases, adding or changing + PKGNAMEPREFIX or + PKGNAMESUFFIX should + suffice. + + + + Add the new subdirectory to the + SUBDIR listing in the parent + directory Makefile. You + can run make checksubdirs in + the parent directory to check this. + + + + If the port changed categories, modify the + CATEGORIES line of the port's + Makefile accordingly + + + + Add an entry to + ports/MOVED, if you remove + the original port. + + + + Commit all changes on one commit. + + + + + + When removing a port: + + + + 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 + grep -r of the ports + collection is recommended. + + + + Remove the old port and the + old SUBDIR entry. + + + + Add an entry to + ports/MOVED. + + + + + + After repo moves (rename + operations where a port is copied and the old + location is removed): + + + + Follow the same steps that are outlined in + the previous two entries, to activate the new + location of the port and remove the old + one. + + + + + + + + + + Ports Freeze + + + + 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. For more information + on how to merge commits to the quarterly branch, see + . + + + + + + Creating a New Category + + + + 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 &a.portmgr;, it is their + decision whether or not to approve it. If they do, it + is their responsibility to do the following: + + + + Perform any needed moves. (This only applies + to physical categories.) + + + + Update the VALID_CATEGORIES + definition in + ports/Mk/bsd.port.mk. + + + + Assign the PR back to you. + + + + + + + + What do I need to do to implement a new physical + category? + + + + + + Upgrade each moved port's + Makefile. Do not connect the + new category to the build yet. + + To do this, you will need to: + + + + Change the port's + CATEGORIES (this was the + point of the exercise, remember?) The new + category should be listed + first. This will help to + ensure that the PKGORIGIN is + correct. + + + + Run a make describe. + Since the top-level + make index that you will be + running in a few steps is an iteration of + make describe over the entire + ports hierarchy, catching any errors here will + save you having to re-run that step later + on. + + + + If you want to be really thorough, now + might be a good time to run + &man.portlint.1;. + + + + + + Check that the PKGORIGINs are + correct. The ports system uses each port's + CATEGORIES entry to create its + PKGORIGIN, which is used to + connect installed packages to the port directory + they were built from. If this entry is wrong, + common port tools like &man.pkg.version.1; and + &man.portupgrade.1; fail. + + To do this, use the + chkorigin.sh tool, as follows: + env + PORTSDIR=/path/to/ports + sh -e + /path/to/ports/Tools/scripts/chkorigin.sh. + This will check every port in + the ports tree, even those not connected to the + build, so you can run it directly after the move + operation. Hint: do not forget to look at the + PKGORIGINs of any slave ports of + the ports you just moved! + + + + On your own local system, test the proposed + changes: first, comment out the + SUBDIR entries in the old ports' + categories' Makefiles; then + enable building the new category in + ports/Makefile. Run + make checksubdirs in the affected + category directories to check the + SUBDIR entries. Next, in the + ports/ + directory, run make index. This + can take over 40 minutes on even modern systems; + however, it is a necessary step to prevent problems + for other people. + + + + Once this is done, you can commit the updated + ports/Makefile to connect the + new category to the build and also commit the + Makefile changes for the old + category or categories. + + + + Add appropriate entries to + ports/MOVED. + + + + Update the documentation by modifying the + following: + + + + the list + of categories in the Porter's + Handbook + + + + + doc/en_US.ISO8859-1/htdocs/ports. + Note that these are now displayed by sub-groups, + as specified in + doc/en_US.ISO8859-1/htdocs/ports/categories.descriptions. + + + + (Note: these are in the docs, not the ports, + repository). If you are not a docs committer, you + will need to submit a PR for this. + + + + Only once all the above have been done, and no + one is any longer reporting problems with the new + ports, should the old ports be deleted from their + previous locations in the repository. + + + + It is not necessary to manually update the + ports web + pages to reflect the new category. This is + done automatically via the change to + en_US.ISO8859-1/htdocs/ports/categories + and the automated rebuild of + INDEX. + + + + + + What do I need to do to implement a new virtual + category? + + + + This is much simpler than a physical category. You + only need to modify the following: + + + + the list + of categories in the Porter's + Handbook + + + + en_US.ISO8859-1/htdocs/ports/categories + + + + + + + + Miscellaneous Questions + + + + 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. + + + + + + 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. + + + + + + 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 + &a.portmgr; is very protective of + ports/Mk/bsd.port*.mk so do not + commit changes to those files unless you want to face + their wra(i)th. + + + + + + What is the proper procedure for updating the + checksum for a port's distfile when the file changes + without a version change? + + + + When the checksum for a port's distfile is updated + due to the author updating the file without changing the + port's revision, the commit message should include 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. + + + + + + What is the procedure to request authorization for + merging a commit to the quarterly branch? + + + + When doing the commit, add the branch name to the + MFH: line, for example: + + MFH: 2014Q1 + + It will automatically notify &a.ports-secteam; and + &a.portmgr;. They will then decide if the commit can be + merged and answer with the procedure. + + If the commit has already been made, send an email + to &a.ports-secteam; and &a.portmgr; with the revision + number and a small description of why the commit needs + to be merged. + + A script is provided to automate merging a specific + commit: ports/Tools/scripts/mfh. + It is used as follows: + + &prompt.user; /usr/ports/Tools/scripts/mfh 2015Q1 380362 + U 2015Q1 +Checked out revision 380443. +A 2015Q1/security +Updating '2015Q1/security/rubygem-sshkit': +A 2015Q1/security/rubygem-sshkit +A 2015Q1/security/rubygem-sshkit/Makefile +A 2015Q1/security/rubygem-sshkit/distinfo +A 2015Q1/security/rubygem-sshkit/pkg-descr +Updated to revision 380443. +--- Merging r380362 into '2015Q1': +U 2015Q1/security/rubygem-sshkit/Makefile +U 2015Q1/security/rubygem-sshkit/distinfo +--- Recording mergeinfo for merge of r380362 into '2015Q1': + U 2015Q1 +--- Recording mergeinfo for merge of r380362 into '2015Q1/security': + G 2015Q1/security +--- Eliding mergeinfo from '2015Q1/security': + U 2015Q1/security +--- Recording mergeinfo for merge of r380362 into '2015Q1/security/rubygem-sshkit': + G 2015Q1/security/rubygem-sshkit +--- Eliding mergeinfo from '2015Q1/security/rubygem-sshkit': + U 2015Q1/security/rubygem-sshkit + M 2015Q1 +M 2015Q1/security/rubygem-sshkit/Makefile +M 2015Q1/security/rubygem-sshkit/distinfo +Index: 2015Q1/security/rubygem-sshkit/Makefile +=================================================================== +--- 2015Q1/security/rubygem-sshkit/Makefile (revision 380443) ++++ 2015Q1/security/rubygem-sshkit/Makefile (working copy) +@@ -2,7 +2,7 @@ + # $FreeBSD$ + + PORTNAME= sshkit +-PORTVERSION= 1.6.1 ++PORTVERSION= 1.7.0 + CATEGORIES= security rubygems + MASTER_SITES= RG + +Index: 2015Q1/security/rubygem-sshkit/distinfo +=================================================================== +--- 2015Q1/security/rubygem-sshkit/distinfo (revision 380443) ++++ 2015Q1/security/rubygem-sshkit/distinfo (working copy) +@@ -1,2 +1,2 @@ +-SHA256 (rubygem/sshkit-1.6.1.gem) = 8ca67e46bb4ea50fdb0553cda77552f3e41b17a5aa919877d93875dfa22c03a7 +-SIZE (rubygem/sshkit-1.6.1.gem) = 135680 ++SHA256 (rubygem/sshkit-1.7.0.gem) = 90effd1813363bae7355f4a45ebc8335a8ca74acc8d0933ba6ee6d40f281a2cf ++SIZE (rubygem/sshkit-1.7.0.gem) = 136192 +Index: 2015Q1 +=================================================================== +--- 2015Q1 (revision 380443) ++++ 2015Q1 (working copy) + +Property changes on: 2015Q1 +___________________________________________________________________ +Modified: svn:mergeinfo + Merged /head:r380362 +Do you want to commit? (no = start a shell) [y/n] + + At that point, the script will either open a shell + for you to fix things, or open your text editor with the + commit message all prepared and then commit the + merge. + + The script assumes that you can connect to + repo.FreeBSD.org with + SSH directly, so if your + local login name is different than your &os; cluster + account, you need a few lines in your + ~/.ssh/config: + + Host repo.freebsd.org # Can be *.freebsd.org + User freebsd-login + + + + + + + + Issues Specific to Developers Who Are Not + Committers + + A few people who have access to the &os; machines do not + have commit bits. Almost all of this document will apply to + these developers as well (except things specific to commits and + the mailing list memberships that go with them). In particular, + we recommend that you read: + + + + Administrative + Details + + + + Conventions + + + You should get your mentor to add you to the + Additional Contributors + (doc/en_US.ISO8859-1/articles/contributors/contrib.additional.xml), + if you are not already listed there. + + + + + Developer + Relations + + + + SSH Quick-Start + Guide + + + + The &os; Committers' Big List + of Rules + + + + + + + Information About &ga; + + As of December 12, 2012, &ga; was enabled on the + &os; Project website to collect anonymized usage statistics + regarding usage of the site. The information collected is + valuable to the &os; Documentation Project, in order to + identify various problems on the &os; website. + + + &ga; General Policy + + The &os; Project takes visitor privacy very + seriously. As such, the &os; Project website honors the + Do Not Track header before + fetching the tracking code from Google. For more information, + please see the + &os; + Privacy Policy. + + &ga; access is not arbitrarily + allowed — access must be requested, voted on by the + &a.doceng;, and explicitly granted. + + Requests for &ga; data must include a specific purpose. + For example, a valid reason for requesting access would be + to see the most frequently used web browsers when + viewing &os; web pages to ensure page rendering speeds are + acceptable. + + Conversely, to see what web browsers are most + frequently used (without stating + why) would be rejected. + + All requests must include the timeframe for which the data + would be required. For example, it must be explicitly stated + if the requested data would be needed for a timeframe covering + a span of 3 weeks, or if the request would be one-time + only. + + Any request for &ga; data without a clear, reasonable + reason beneficial to the &os; Project will be + rejected. + + + + Data Available Through &ga; + + A few examples of the types of &ga; data available + include: + + + + Commonly used web browsers + + + + Page load times + + + + Site access by language + + + + + + + Miscellaneous Questions + + + + + Why are trivial or cosmetic changes to files on a + vendor branch a bad idea? + + + + + + From now on, every new vendor release of that file + will need to have patches merged in by hand. + + + + From now on, every new vendor release of that file + will need to have patches + verified by hand. + + + + + + + + How do I add a new file to a branch? + + + + To add a file onto a branch, simply checkout or update + to the branch you want to add to and then add the file + using the add operation as you normally would. This works + fine for the doc and + ports trees. The + src tree uses SVN and requires more + care because of the mergeinfo + properties. See the + Subversion Primer + for details on how to perform an MFC. + + + + + + How do I access people.FreeBSD.org to + put up personal or project information? + + + + people.FreeBSD.org is + the same as freefall.FreeBSD.org. + Just create a public_html directory. + Anything you place in that directory will automatically be + visible under http://people.FreeBSD.org/. + + + + + + Where are the mailing list archives stored? + + + + The mailing lists are archived under + /local/mail on freefall.FreeBSD.org. + + + + + + I would like to mentor a new committer. What process + do I need to follow? + + + + See the New + Account Creation Procedure document on the + internal pages. + + + + + + + Benefits and Perks for &os; Comitters + + + Recognition + + Recognition as a competent software engineer is the + longest lasting value. In addition, getting a chance to work + with some of the best people that every engineer would dream + of meeting is a great perk! + + + + FreeBSD Mall + + &os; committers can get a free 4-CD or DVD set at + conferences from + &os; Mall, + Inc.. + + + + <acronym>IRC</acronym> + + In addition, developers may request a cloaked hostmask + for their account on the Freenode IRC network in the form + of + freebsd/developer/freefall + name or + freebsd/developer/NickServ + name. To request a cloak, send an email to + &a.irc.email; with your requested hostmask and NickServ + account name. + + + + <systemitem + class="domainname">Gandi.net</systemitem> + + Gandi provides website hosting, cloud computing, domain + registration, and X.509 certificate services. + + Gandi offers an E-rate discount to all &os; developers. + Send mail to non-profit@gandi.net using your + @freebsd.org mail address, and indicate + your Gandi handle. + + +
Property changes on: user/jgh/committers-guide/article.xml ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/xml \ No newline at end of property