From owner-svn-src-user@freebsd.org Thu Feb 25 20:43:27 2016 Return-Path: Delivered-To: svn-src-user@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 02B65AB4B66 for ; Thu, 25 Feb 2016 20:43:27 +0000 (UTC) (envelope-from jgh@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 8E7AADBD; Thu, 25 Feb 2016 20:43:26 +0000 (UTC) (envelope-from jgh@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id u1PKhPxK079761; Thu, 25 Feb 2016 20:43:25 GMT (envelope-from jgh@FreeBSD.org) Received: (from jgh@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id u1PKhPL6079759; Thu, 25 Feb 2016 20:43:25 GMT (envelope-from jgh@FreeBSD.org) Message-Id: <201602252043.u1PKhPL6079759@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: jgh set sender to jgh@FreeBSD.org using -f From: Jason Helfman Date: Thu, 25 Feb 2016 20:43:25 +0000 (UTC) To: src-committers@freebsd.org, svn-src-user@freebsd.org Subject: svn commit: r296065 - user/jgh/committers-guide X-SVN-Group: user MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-src-user@freebsd.org X-Mailman-Version: 2.1.20 Precedence: list List-Id: "SVN commit messages for the experimental " user" src tree" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 25 Feb 2016 20:43:27 -0000 Author: jgh (doc,ports committer) Date: Thu Feb 25 20:43:25 2016 New Revision: 296065 URL: https://svnweb.freebsd.org/changeset/base/296065 Log: - add workspace for committers guide Added: user/jgh/committers-guide/ user/jgh/committers-guide/Makefile (contents, props changed) user/jgh/committers-guide/article.xml (contents, props changed) Added: user/jgh/committers-guide/Makefile ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ user/jgh/committers-guide/Makefile Thu Feb 25 20:43:25 2016 (r296065) @@ -0,0 +1,23 @@ +# +# $FreeBSD$ +# +# Article: The FreeBSD Committers Guide + +DOC?= article + +FORMATS?= html +WITH_ARTICLE_TOC?= YES + +INSTALL_COMPRESSED?= gz +INSTALL_ONLY_COMPRESSED?= + +SRCS= article.xml + +IMAGES_LIB= callouts/1.png +IMAGES_LIB+= callouts/2.png +IMAGES_LIB+= callouts/3.png + +URL_RELPREFIX?= ../../../.. +DOC_PREFIX?= ${.CURDIR}/../../.. + +.include "${DOC_PREFIX}/share/mk/doc.project.mk" Added: user/jgh/committers-guide/article.xml ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ user/jgh/committers-guide/article.xml Thu Feb 25 20:43:25 2016 (r296065) @@ -0,0 +1,5043 @@ + + +]> + +
+ + + Committer's Guide + + + The &os; Documentation Project + + + + 1999 + 2000 + 2001 + 2002 + 2003 + 2004 + 2005 + 2006 + 2007 + 2008 + 2009 + 2010 + 2011 + 2012 + 2013 + 2014 + 2015 + The &os; Documentation Project + + + + &tm-attrib.freebsd; + &tm-attrib.coverity; + &tm-attrib.ibm; + &tm-attrib.intel; + &tm-attrib.sparc; + &tm-attrib.general; + + + $FreeBSD$ + + $FreeBSD$ + + + This document provides information for the &os; + committer community. All new committers should read this + document before they start, and existing committers are + strongly encouraged to review it from time to time. + + Almost all &os; developers have commit rights to one or + more repositories. However, a few developers do not, and some + of the information here applies to them as well. (For + instance, some people only have rights to work with the + Problem Report database). Please see + for more information. + + This document may also be of interest to members of the + &os; community who want to learn more about how the project + works. + + + + + Administrative Details + + + + + + + + Login Methods + &man.ssh.1;, protocol 2 only + + + + Main Shell Host + freefall.FreeBSD.org + + + + src/ Subversion + Root + svn+ssh://repo.FreeBSD.org/base + (see also ). + + + + doc/ Subversion + Root + svn+ssh://repo.FreeBSD.org/doc + (see also ). + + + + ports/ Subversion + Root + + svn+ssh://repo.FreeBSD.org/ports + (see also ). + + + + Internal Mailing Lists + developers (technically called all-developers), + doc-developers, doc-committers, ports-developers, + ports-committers, src-developers, src-committers. (Each + project repository has its own -developers and + -committers mailing lists. Archives for these lists can + be found in the files + /local/mail/repository-name-developers-archive + and + /local/mail/repository-name-committers-archive + on the FreeBSD.org + cluster.) + + + + + Core Team monthly + reports + /home/core/public/monthly-reports + on the FreeBSD.org + cluster. + + + + Ports Management Team monthly + reports + /home/portmgr/public/monthly-reports + on the FreeBSD.org + cluster. + + + + Noteworthy src/ SVN + Branches + + stable/8 (8.X-STABLE), + stable/9 (9.X-STABLE), + stable/10 (10.X-STABLE), + head (-CURRENT) + + + + + + &man.ssh.1; is required to connect to the project hosts. + For more information, see . + + Useful links: + + + + &os; + Project Internal Pages + + + + &os; + Project Hosts + + + + &os; + Project Administrative Groups + + + + + + Open<acronym>PGP</acronym> Keys for &os; + + Cryptographic keys conforming to the + OpenPGP (Pretty Good + Privacy) standard are used by the &os; project to + authenticate committers. Messages carrying important + information like public SSH keys can be + signed with the OpenPGP key to prove that + they are really from the committer. See + PGP & + GPG: Email for the Practical Paranoid by Michael Lucas + and + for more information. + + + Creating a Key + + Existing keys can be used, but should be checked with + doc/head/share/pgpkeys/checkkey.sh + first. + + For those who do not yet have an + OpenPGP key, or need a new key to meet &os; + security requirements, here we show how to generate + one. + + + + + Install + security/gnupg. Enter + these lines in ~/.gnupg/gpg.conf to + set minimum acceptable defaults: + + fixed-list-mode +keyid-format 0xlong +personal-digest-preferences SHA512 SHA384 SHA256 SHA224 +default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 BZIP2 ZLIB ZIP Uncompressed +use-agent +verify-options show-uid-validity +list-options show-uid-validity +sig-notation issuer-fpr@notations.openpgp.fifthhorseman.net=%g +cert-digest-algo SHA512 + + + + Generate a key: + + &prompt.user; gpg --full-gen-key +gpg (GnuPG) 2.1.8; Copyright (C) 2015 Free Software Foundation, Inc. +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. + +Warning: using insecure memory! +Please select what kind of key you want: + (1) RSA and RSA (default) + (2) DSA and Elgamal + (3) DSA (sign only) + (4) RSA (sign only) +Your selection? 1 +RSA keys may be between 1024 and 4096 bits long. +What keysize do you want? (2048) 2048 +Requested keysize is 2048 bits +Please specify how long the key should be valid. + 0 = key does not expire + <n> = key expires in n days + <n>w = key expires in n weeks + <n>m = key expires in n months + <n>y = key expires in n years +Key is valid for? (0) 3y +Key expires at Wed Nov 4 17:20:20 2015 MST +Is this correct? (y/N) y + +GnuPG needs to construct a user ID to identify your key. + +Real name: Chucky Daemon +Email address: notreal@example.com +Comment: +You selected this USER-ID: + "Chucky Daemon <notreal@example.com>" + +Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o +You need a Passphrase to protect your secret key. + + + + 2048-bit keys with a three-year expiration provide + adequate protection at present (2013-12). + describes the situation in more detail. + + + + A three year key lifespan is short enough to + obsolete keys weakened by advancing computer power, + but long enough to reduce key management + problems. + + + + Use your real name here, preferably matching that + shown on government-issued ID to + make it easier for others to verify your identity. + Text that may help others identify you can be entered + in the Comment section. + + + + After the email address is entered, a passphrase is + requested. Methods of creating a secure passphrase are + contentious. Rather than suggest a single way, here are + some links to sites that describe various methods: , + , + , + . + + + + Protect your private key and passphrase. If either the + private key or passphrase may have been compromised or + disclosed, immediately notify + accounts@FreeBSD.org and revoke the key. + + Committing the new key is shown in + . + + + + + Kerberos and LDAP web Password for &os; Cluster + + The &os; cluster requires a Kerberos password to access + certain services. The Kerberos password also serves as the + LDAP web password, since LDAP is proxying to Kerberos in the + cluster. Some of the services + which require this include: + + + + Bugzilla + + + Jenkins + + + + To create a new Kerberos account in the &os; cluster, or to + reset a Kerberos password for an existing account using a random + password generator: + + &prompt.user; ssh kpasswd.freebsd.org + + + This must be done from a machine outside of the &os;.org + cluster. + + + A Kerberos password can also be set manually + by logging into freefall.FreeBSD.org and + running: + + &prompt.user; kpasswd + + + Unless you have used the Kerberos-authenticated services + of the &os;.org cluster previously, + Client unknown will be shown. This + error means that the + ssh kpasswd.freebsd.org method shown above + must be used first to initialize your Kerberos account. + + + + + + Commit Bit Types + + The &os; repository has a number of components which, when + combined, support the basic operating system source, + documentation, third party application ports infrastructure, and + various maintained utilities. When &os; commit bits are + allocated, the areas of the tree where the bit may be used are + specified. Generally, the areas associated with a bit reflect + who authorized the allocation of the commit bit. Additional + areas of authority may be added at a later date: when this + occurs, the committer should follow normal commit bit allocation + procedures for that area of the tree, seeking approval from the + appropriate entity and possibly getting a mentor for that area + for some period of time. + + + + + + Committer Type + Responsible + Tree Components + + + + src + core@ + src/, doc/ subject to appropriate review + + + + doc + doceng@ + doc/, ports/, src/ documentation + + + + ports + portmgr@ + ports/ + + + + + + Commit bits allocated prior to the development of the notion + of areas of authority may be appropriate for use in many parts + of the tree. However, common sense dictates that a committer + who has not previously worked in an area of the tree seek review + prior to committing, seek approval from the appropriate + responsible party, and/or work with a mentor. Since the rules + regarding code maintenance differ by area of the tree, this is + as much for the benefit of the committer working in an area of + less familiarity as it is for others working on the tree. + + Committers are encouraged to seek review for their work as + part of the normal development process, regardless of the area + of the tree where the work is occurring. + + + Policy for Committer Activity in Other Trees + + + + All committers may modify + base/head/share/misc/committers-*.dot, + base/head/usr.bin/calendar/calendars/calendar.freebsd, + and + ports/head/astro/xearth/files. + + + + doc committers may commit + documentation changes to src + files, such as man pages, READMEs, fortune databases, + calendar files, and comment fixes without approval from a + src committer, subject to the normal care and tending of + commits. + + + + Any committer may make changes to any other tree + with an "Approved by" from a non-mentored committer with + the appropriate bit. + + + + Committers can aquire an additional bit by the usual + process of finding a mentor who will propose them to core, + doceng, or portmgr, as appropriate. When approved, they + will be added to 'access' and the normal mentoring period + will ensue, which will involve a continuing of + Approved by for some period. + + + + "Approved by" is only acceptable from non-mentored src + committers -- mentored committers can provide a "Reviewed + by" but not an "Approved by". + + + + + + + Subversion Primer + + It is assumed that you are already familiar with the basic + operation of Subversion. If not, start by reading the + Subversion + Book. + + + Introduction + + The &os; source repository switched from + CVS to Subversion on May 31st, 2008. The + first real SVN commit is + r179447. + + The &os; doc/www repository switched + from CVS to Subversion on May 19th, 2012. + The first real SVN commit is + r38821. + + The &os; ports repository switched + from CVS to Subversion on July 14th, 2012. + The first real SVN commit is + r300894. + + Subversion can be installed from the &os; Ports + Collection by issuing these commands: + + &prompt.root; pkg install subversion + + + + + Getting Started + + There are a few ways to obtain a working copy of the tree + from Subversion. This section will explain them. + + + Direct Checkout + + The first is to check out directly from the main + repository. For the src tree, + use: + + &prompt.user; svn checkout svn+ssh://repo.freebsd.org/base/head /usr/src + + For the doc tree, use: + + &prompt.user; svn checkout svn+ssh://repo.freebsd.org/doc/head /usr/doc + + For the ports tree, use: + + &prompt.user; svn checkout svn+ssh://repo.freebsd.org/ports/head /usr/ports + + + Though the remaining examples in this document are + written with the workflow of working with the + src tree in mind, the underlying + concepts are the same for working with the + doc and the ports + tree. + Ports related Subversion operations are listed in + . + + + The above command will check out a + CURRENT source tree as + /usr/src/, + which can be any target directory on the local filesystem. + Omitting the final argument of that command causes the + working copy, in this case, to be named head, + but that can be renamed safely. + + svn+ssh means the + SVN protocol tunnelled over + SSH. The name of the server is + repo.freebsd.org, base + is the path to the repository, and head + is the subdirectory within the repository. + + If your &os; login name is different from your login + name on your local machine, you must either include it in + the URL (for example + svn+ssh://jarjar@repo.freebsd.org/base/head), + or add an entry to your ~/.ssh/config + in the form: + + Host repo.freebsd.org + User jarjar + + This is the simplest method, but it is hard to tell just + yet how much load it will place on the repository. + + + The svn diff does not require + access to the server as SVN stores a + reference copy of every file in the working copy. This, + however, means that Subversion working copies are very + large in size. + + + + + Checkout from a Mirror + + Check out a working copy from a mirror by + substituting the mirror's URL for + svn+ssh://repo.freebsd.org/base. This + can be an official mirror or a mirror maintained by using + svnsync. + + There is a serious disadvantage to this method: every + time something is to be committed, a + svn relocate to the master repository has + to be done, remembering to svn relocate + back to the mirror after the commit. Also, since + svn relocate only works between + repositories that have the same UUID, some hacking of the + local repository's UUID has to occur before it is possible + to start using it. + + The hassle of a local + svnsync mirror probably is not worth it + unless the network connectivity situation or other factors + demand it. If it is needed, see the end of this chapter for + information on how to set one up. + + + + <literal>RELENG_*</literal> Branches and General + Layout + + In svn+ssh://repo.freebsd.org/base, + base refers to the source tree. + Similarly, ports refers to the ports + tree, and so on. These are separate repositories with their + own change number sequences, access controls and commit + mail. + + For the base repository, HEAD refers to the -CURRENT + tree. For example, head/bin/ls is what + would go into /usr/src/bin/ls in a + release. Some key locations are: + + + + /head/ which corresponds to + HEAD, also known as + -CURRENT. + + + + /stable/n + which corresponds to + RELENG_n. + + + + /releng/n.n + which corresponds to + RELENG_n_n. + + + + /release/n.n.n + which corresponds to + RELENG_n_n_n_RELEASE. + + + + /vendor* is the vendor branch + import work area. This directory itself does not + contain branches, however its subdirectories do. This + contrasts with the stable, + releng and + release directories. + + + + /projects and + /user feature a branch work area, + like in Perforce. As above, the + /user directory does not contain + branches itself. + + + + + + &os; Documentation Project Branches and + Layout + + In svn+ssh://repo.freebsd.org/doc, + doc refers to the repository root of + the source tree. + + In general, most &os; Documentation Project work will be + done within the head/ branch of the + documentation source tree. + + &os; documentation is written and/or translated to + various languages, each in a separate + directory in the head/ + branch. + + Each translation set contains several subdirectories for + the various parts of the &os; Documentation Project. A few + noteworthy directories are: + + + + /articles/ contains the source + code for articles written by various &os; + contributors. + + + + /books/ contains the source + code for the different books, such as the + &os; Handbook. + + + + /htdocs/ contains the source + code for the &os; website. + + + + + + &os; Ports Tree Branches and Layout + + In svn+ssh://repo.freebsd.org/ports, + ports refers to the repository root of + the ports tree. + + In general, most &os; port work will be done within the + head/ branch of the ports tree which is + the actual ports tree used to install software. Some other + key locations are: + + + + /branches/RELENG_n_n_n + which corresponds to + RELENG_n_n_n + is used to merge back security updates in preparation + for a release. + + + + /tags/RELEASE_n_n_n + which corresponds to + RELEASE_n_n_n + represents a release tag of the ports tree. + + + + /tags/RELEASE_n_EOL + represents the end of life tag of a specific &os; + branch. + + + + + + + Daily Use + + This section will explain how to perform common day-to-day + operations with Subversion. + + + Help + + SVN has built in help documentation. + It can be accessed by typing the following command: + + &prompt.user; svn help + + Additional information can be found in the + Subversion + Book. + + + + Checkout + + As seen earlier, to check out the &os; head + branch: + + &prompt.user; svn checkout svn+ssh://repo.freebsd.org/base/head /usr/src + + At some point, more than just HEAD + will probably be useful, for instance when merging changes + to stable/7. Therefore, it may be useful to have a partial + checkout of the complete tree (a full checkout would be very + painful). + + To do this, first check out the root of the + repository: + + &prompt.user; svn checkout --depth=immediates svn+ssh://repo.freebsd.org/base + + This will give base with all the + files it contains (at the time of writing, just + ROADMAP.txt) and empty subdirectories + for head, stable, + vendor and so on. + + Expanding the working copy is possible. Just change the + depth of the various subdirectories: + + &prompt.user; svn up --set-depth=infinity base/head +&prompt.user; svn up --set-depth=immediates base/release base/releng base/stable + + The above command will pull down a full copy of + head, plus empty copies of every + release tag, every + releng branch, and every + stable branch. + + If at a later date merging to + 7-STABLE is required, expand the working + copy: + + &prompt.user; svn up --set-depth=infinity base/stable/7 + + Subtrees do not have to be expanded completely. For + instance, expanding only stable/7/sys and + then later expand the rest of + stable/7: + + &prompt.user; svn up --set-depth=infinity base/stable/7/sys +&prompt.user; svn up --set-depth=infinity base/stable/7 + + Updating the tree with svn update + will only update what was previously asked for (in this + case, head and + stable/7; it will not pull down the whole + tree. + + + Decreasing the depth of a working copy is not + possible. + + + + + Anonymous Checkout + + It is possible to anonymously check out the &os; + repository with Subversion. This will give access to a + read-only tree that can be updated, but not committed back + to the main repository. To do this, use the following + command: + + &prompt.user; svn co https://svn.FreeBSD.org/base/head /usr/src + + More details on using Subversion this way can be found + in Using + Subversion. + + + + Updating the Tree + + To update a working copy to either the latest revision, + or a specific revision: + + &prompt.user; svn update +&prompt.user; svn update -r12345 + + + + Status + + To view the local changes that have been made to the + working copy: + + &prompt.user; svn status + + To show local changes and files that are out-of-date + do: + + &prompt.user; svn status --show-updates + + + + Editing and Committing + + Unlike Perforce, SVN does not need to + be told in advance about file editing. + + To commit all changes in + the current directory and all subdirectories: + + &prompt.user; svn commit + + To commit all changes in, for example, + lib/libfetch/ + and + usr/bin/fetch/ + in a single operation: + + &prompt.user; svn commit lib/libfetch usr/bin/fetch + + There is also a commit wrapper for the ports tree to + handle the properties and sanity checking your + changes: + + &prompt.user; /usr/ports/Tools/scripts/psvn commit + + + + Adding and Removing Files + + + Before adding files, get a copy of auto-props.txt + (there is also a + ports tree specific version) and add it to + ~/.subversion/config according to the + instructions in the file. If you added something before + reading this, use svn rm --keep-local + for just added files, fix your config file and re-add them + again. The initial config file is created when you first + run a svn command, even something as simple as + svn help. + + + Files are added to a + SVN repository with svn + add. To add a file named + foo, edit it, then: + + &prompt.user; svn add foo + + + Most new source files should include a + $&os;$ string near the + start of the file. On commit, svn will + expand the $&os;$ string, + adding the file path, revision number, date and time of + commit, and the username of the committer. Files which + cannot be modified may be committed without the + $&os;$ string. + + + Files can be removed with svn + remove: + + &prompt.user; svn remove foo + + Subversion does not require deleting the file before + using svn rm, and indeed complains if + that happens. + + It is possible to add directories with + svn add: + + &prompt.user; mkdir bar +&prompt.user; svn add bar + + Although svn mkdir makes this easier + by combining the creation of the directory and the adding of + it: + + &prompt.user; svn mkdir bar + + Like files, directories are removed with + svn rm. There is no separate command + specifically for removing directories. + + &prompt.user; svn rm bar + + + + Copying and Moving Files + + This command creates a copy of + foo.c named bar.c, + with the new file also under version control: + + &prompt.user; svn copy foo.c bar.c + + The example above is equivalent to: + + &prompt.user; cp foo.c bar.c +&prompt.user; svn add bar.c + + To move and rename a file: *** DIFF OUTPUT TRUNCATED AT 1000 LINES ***