Index: user/jgh/committers-guide/article.xml =================================================================== --- user/jgh/committers-guide/article.xml (revision 296246) +++ user/jgh/committers-guide/article.xml (nonexistent) @@ -1,5227 +0,0 @@ - - -]> - -
- - - Committer's Guide - - - The &os; Documentation Project - - - - 1999 - 2000 - 2001 - 2002 - 2003 - 2004 - 2005 - 2006 - 2007 - 2008 - 2009 - 2010 - 2011 - 2012 - 2013 - 2014 - 2015 - 2016 - 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 - conf/mentors. This file is in the - svnadmin branch of each - repository: - - - - - - src - base/svnadmin/conf/mentors - - - - doc - doc/svnadmin/conf/mentors - - - - ports - ports/svnadmin/conf/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 - - Phabricator is an online service that provides pre-commit - code review workflows. Revisions are created in Phabricator - with a command-line tool, reviewed by developers and committed - once changes have been accepted. - - This section describes how to use Phabricator in the context - of &os; source and ports trees by using the service hosted at - - https://reviews.freebsd.org/ - - - Setup - - Before being able to create revisions for code review, - an account is required. Additionally, command-line client - tools need to be installed. - - - - - Create an account by visiting Phabricator - Registration. Please use a &os; email address - when registrating so Phabricator admins can track who - you are. - - - - Install the client package. - - &prompt.root; pkg install php5-arcanist - - - - Setup the client resource configuration file - ~/.arcrc with the certificates - required to access the online service. This process - requires manually copy/pasting a cookie provided by the - online service. Do this by typing the command below and - following the online instructions. - - &prompt.root; arc install-certificate https://reviews.freebsd.org - - After completion, configure Arcanist to use https://reviews.freebsd.org - as the default URI: - - &prompt.root; arc set-config default https://reviews.freebsd.org/ - - - - - - Create a Revision - - Once you have finished preparing a change locally, you - are ready to send it out for review. - - Please make sure that your changeset does one thing - (and one thing only) so the review process goes smoothly. - Small and self-contained changes are much easier to - review! - - Phabricator has two groups of participants in a review: - Reviewers and Subscribers. Individuals and project groups - may be Reviewers, and at least one reviewer must accept a - revision for it to proceed. Subscribers are notified of a - revision and any changes, but are not required to accept a - revision. Subscribers may be individuals, project groups, - and mailing lists. - - - - - - - From the top of the SVN or git tree, run the - following command to create a new revision for the - given paths: - - &prompt.user; arc diff --create /path/to/file - - - - Executing the previous step will open an editor with - the following template to fill in: - - Replace this line with your Revision Title - -Summary: - -Test Plan: - -Reviewers: - -Subscribers: - -# NEW DIFFERENTIAL REVISION -# Describe the changes in this new revision. -# -# arc could not identify any existing revision in your working copy. -# If you intended to update an existing revision, use: -# -# $ arc diff --update revision - - Use these guidelines for filling in the template: - - - - - The Revision Title is - mandatory. This is a one line description of the - change. - - - - The Summary is optional. - However, this should contain verbatim content of the - commit message to be used when submitting the - change. - - - - The Test Plan is optional. - Describe how to test the patch and how the reviewer - may test it. If it is difficult to draft a plan, - please reconsider. - - - - The Reviewers is optional. - However, &os; committers that are expected to review - the patch may be listed here. If such committers have - accounts on Phabricator, they will automatically be - notified of your submission. Reviewers may be added - by their nickname: - - &prompt.user; arc diff --reviewers nick - - or by project: - - &prompt.user; arc diff --reviewers #portmgr - - - - Subscribers may be individuals, project groups, - and mailing lists. - - - - The Differential Revision cannot be added here, - however it must be in the svn commit message. - - - - - - After saving and exiting your editor, the changeset - will be creating in Phabricator and Arcanist will print - a tracking link for your revision: - - https://reviews.freebsd.org/DXXX - - - - - - - - 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 ___________________________________________________________________ Deleted: svn:eol-style ## -1 +0,0 ## -native \ No newline at end of property Deleted: svn:keywords ## -1 +0,0 ## -FreeBSD=%H \ No newline at end of property Deleted: svn:mime-type ## -1 +0,0 ## -text/xml \ No newline at end of property Index: user/jgh/committers-guide/Makefile =================================================================== --- user/jgh/committers-guide/Makefile (revision 296246) +++ user/jgh/committers-guide/Makefile (nonexistent) @@ -1,26 +0,0 @@ -# -# $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 -IMAGES_LIB+= callouts/4.png -IMAGES_LIB+= callouts/5.png -IMAGES_LIB+= callouts/6.png - -URL_RELPREFIX?= ../../../.. -DOC_PREFIX?= ${.CURDIR}/../../.. - -.include "${DOC_PREFIX}/share/mk/doc.project.mk" Property changes on: user/jgh/committers-guide/Makefile ___________________________________________________________________ Deleted: svn:eol-style ## -1 +0,0 ## -native \ No newline at end of property Deleted: svn:keywords ## -1 +0,0 ## -FreeBSD=%H \ No newline at end of property Deleted: svn:mime-type ## -1 +0,0 ## -text/plain \ No newline at end of property