From owner-svn-doc-head@FreeBSD.ORG Sun Jan 5 22:45:51 2014 Return-Path: Delivered-To: svn-doc-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id D8FB58F3; Sun, 5 Jan 2014 22:45:51 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id C26451B1D; Sun, 5 Jan 2014 22:45:51 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.7/8.14.7) with ESMTP id s05MjpJH015143; Sun, 5 Jan 2014 22:45:51 GMT (envelope-from wblock@svn.freebsd.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.7/8.14.7/Submit) id s05MjpKv015142; Sun, 5 Jan 2014 22:45:51 GMT (envelope-from wblock@svn.freebsd.org) Message-Id: <201401052245.s05MjpKv015142@svn.freebsd.org> From: Warren Block Date: Sun, 5 Jan 2014 22:45:51 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r43437 - head/en_US.ISO8859-1/articles/committers-guide X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 05 Jan 2014 22:45:51 -0000 Author: wblock Date: Sun Jan 5 22:45:51 2014 New Revision: 43437 URL: http://svnweb.freebsd.org/changeset/doc/43437 Log: Whitespace-only fixes, translators please ignore. Modified: head/en_US.ISO8859-1/articles/committers-guide/article.xml Modified: head/en_US.ISO8859-1/articles/committers-guide/article.xml ============================================================================== --- head/en_US.ISO8859-1/articles/committers-guide/article.xml Sun Jan 5 21:59:57 2014 (r43436) +++ head/en_US.ISO8859-1/articles/committers-guide/article.xml Sun Jan 5 22:45:51 2014 (r43437) @@ -3,11 +3,17 @@ "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd" [ ]> -
- Committer's Guide - - The &os; Documentation Project +
+ + + Committer's Guide + + + The &os; Documentation Project + 1999 @@ -52,7 +58,8 @@ 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. + 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 @@ -75,28 +82,36 @@ Main Shell Host - freefall.FreeBSD.org + freefall.FreeBSD.org src/ Subversion Root - svn+ssh://svn.FreeBSD.org/base - (see also ). + svn+ssh://svn.FreeBSD.org/base + (see also ). doc/ Subversion Root - svn+ssh://svn.FreeBSD.org/doc - (see also ). + svn+ssh://svn.FreeBSD.org/doc + (see also ). ports/ Subversion Root - svn+ssh://svn.FreeBSD.org/ports - (see also ). + + svn+ssh://svn.FreeBSD.org/ports + (see also ). @@ -110,7 +125,8 @@ /home/mail/repository-name-developers-archive and /home/mail/repository-name-committers-archive - on the FreeBSD.org + on the FreeBSD.org cluster.) @@ -119,7 +135,8 @@ Core Team monthly reports /home/core/public/monthly-reports - on the FreeBSD.org + on the FreeBSD.org cluster. @@ -127,7 +144,8 @@ Ports Management Team monthly reports /home/portmgr/public/monthly-reports - on the FreeBSD.org + on the FreeBSD.org cluster. @@ -156,13 +174,14 @@ - &os; Project - Hosts + &os; + Project Hosts - &os; Project - Administrative Groups + &os; + Project Administrative Groups @@ -171,12 +190,12 @@ 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 + 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 2048-bit keys with a three-year expiration provide adequate protection at present (2013-12). describes the situation in more detail. + xlink:href="http://danielpocock.com/rsa-key-sizes-2048-or-4096-bits"/> + describes the situation in more detail. @@ -288,8 +308,8 @@ You need a Passphrase to protect your se Commit Bit Types - The &os; repository has a number of components which, - when combined, support the basic operating system source, + 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 @@ -387,11 +407,14 @@ You need a Passphrase to protect your se It is assumed that you are already familiar with the basic operation of Subversion. If not, start by reading the - Subversion Book. + Subversion + Book. - There + There is a list of things missing in Subversion when compared to - CVS. The notes at http://people.freebsd.org/~peter/svn_notes.txt + CVS. The notes at http://people.freebsd.org/~peter/svn_notes.txt might also be useful. @@ -525,11 +548,12 @@ You need a Passphrase to protect your se 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. + 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 @@ -694,13 +718,13 @@ You need a Passphrase to protect your se &os; Ports Tree Branches and Layout In svn+ssh://svn.freebsd.org/ports, - ports refers to the repository root of the - ports tree. + 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: + 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: @@ -815,12 +839,14 @@ You need a Passphrase to protect your se 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: + to the main repository. To do this, use the following + command: &prompt.user; svn co https://svn0.us-west.FreeBSD.org/base/head /usr/src Select the closest mirror and verify the mirror server - certificate from the list of Subversion + certificate from the list of Subversion mirror sites. @@ -860,9 +886,10 @@ You need a Passphrase to protect your se &prompt.user; svn commit - To commit all changes in, for example, lib/libfetch/ - and usr/bin/fetch/ - in a single operation: + 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 @@ -878,16 +905,17 @@ You need a Passphrase to protect your se 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 + 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. @@ -900,9 +928,9 @@ You need a Passphrase to protect your se Most new source files should include a - $&os;$ string near the start of the - file. On commit, svn will expand - the $&os;$ string, + $&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 @@ -1219,22 +1247,23 @@ You need a Passphrase to protect your se 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. + 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. + 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. @@ -1288,32 +1317,29 @@ You need a Passphrase to protect your se Changes to kernel code should be merged to - sys/. For - instance, a change to the &man.ichwd.4; driver 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/dev/ichwd/. - Likewise, a change to the TCP/IP stack should be - merged to sys/, - not sys/netinet/. + sys/netinet/. - Changes to code under - etc/ should be - merged at etc/, - not below it. + 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 + 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. @@ -1322,41 +1348,39 @@ You need a Passphrase to protect your se 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/. + 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/. + 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. + 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. + 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. - + Other changes to share/ + should be merged to the appropriate subdirectory and + not to share/ directly. @@ -1385,14 +1409,14 @@ You need a Passphrase to protect your se 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. + 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. @@ -1489,12 +1513,13 @@ $target - head/$source:$P,$Q,$R As a practical example, consider the following scenario: The changes to netmap.4 in r238987 is to be merged from CURRENT to 9-STABLE. - The file resides in head/share/man/man4 and - 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 file resides in + head/share/man/man4 and 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. @@ -2032,13 +2057,15 @@ U stable/9/share/man/man4/netmap.4 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, + 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 + 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: @@ -2112,8 +2139,8 @@ ControlPersist yes The .ent, .xml, and .xml files listed below exist in the - &os; Documentation Project SVN repository at - svn.FreeBSD.org/doc/. + &os; Documentation Project SVN repository at svn.FreeBSD.org/doc/. If you have been given commit rights to one or more of the @@ -2121,6 +2148,7 @@ ControlPersist yes Steps for New Committers + Add your author entity to head/share/xml/authors.ent; this @@ -2152,7 +2180,8 @@ ControlPersist yes Add yourself to the Developers section - of the Contributors + of the Contributors List (head/en_US.ISO8859-1/articles/contributors/contrib.committers.xml) and remove yourself from the @@ -2180,7 +2209,8 @@ ControlPersist yes &a.des.email; has written a shell script (head/share/pgpkeys/addkey.sh) to - make this extremely simple. See the README + make this extremely simple. See the README file for more information. @@ -2188,8 +2218,10 @@ ControlPersist yes in the Handbook, since the key may be required for positive identification of a committer, e.g., by the &a.admins; for account recovery. A complete keyring of - FreeBSD.org users is - available for download from http://www.FreeBSD.org/doc/pgpkeyring.txt. + FreeBSD.org users is + available for download from http://www.FreeBSD.org/doc/pgpkeyring.txt. @@ -2212,24 +2244,26 @@ ControlPersist yes If you already have an account at the - &os; wiki, - make sure your mentor moves you from the Contributors - group to the Developers - group. Otherwise, consider signing up for an + &os; + wiki, make sure your mentor moves you from the + Contributors + group to the Developers + group. Otherwise, consider signing up for an account so you can publish projects and ideas you are working on. Once you get access to the wiki, you may add yourself - to the - How We + to the How We Got Here, Irc - Nicks, and - Dogs - of FreeBSD pages. + Nicks, and Dogs + of FreeBSD pages. @@ -2266,18 +2300,19 @@ ControlPersist yes - Log into hub.FreeBSD.org and create a - /var/forward/user - (where user is your username) - file containing the e-mail address where you want mail + Log into hub.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 hub often - get accidentally truncated without warning, - so forward it or read it and you will not lose it. + taken up permanent residence on + hub often get + accidentally truncated without warning, 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 @@ -2288,9 +2323,9 @@ ControlPersist yes 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. + directory on freefall.FreeBSD.org + to disable the checks for your email. @@ -2328,201 +2363,199 @@ ControlPersist yes 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 can not - understand more than one. - - - - 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 commiting 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. - - If these are your first - commits then you should have passed them past your - mentor first, and you should list your mentor, as - in ``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: ``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. - - - - 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. + 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 can not understand more than + one. + + + + 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 commiting 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. + + If these are your first commits then you should have + passed them past your mentor first, and you should list + your mentor, as in + ``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: ``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. + + + + 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: foo/12345 Submitted by: John Smith <John.Smith@example.com> - + - - Commit Log for a Commit Needing Review + + 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. + 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 + + 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. + 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 + 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. + 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. - - 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. + 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: foo/54321 + 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: foo/54321 Submitted by: John Smith <John.Smith@example.com> Reviewed by: -arch Obtained from: NetBSD MFC after: 1 month - + @@ -2601,31 +2634,31 @@ MFC after: 1 month