From owner-freebsd-doc@FreeBSD.ORG Mon Jul 28 09:30:02 2008 Return-Path: Delivered-To: freebsd-doc@hub.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 7B00E1065687 for ; Mon, 28 Jul 2008 09:30:02 +0000 (UTC) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (freefall.freebsd.org [IPv6:2001:4f8:fff6::28]) by mx1.freebsd.org (Postfix) with ESMTP id 4BDF68FC1A for ; Mon, 28 Jul 2008 09:30:02 +0000 (UTC) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (gnats@localhost [127.0.0.1]) by freefall.freebsd.org (8.14.2/8.14.2) with ESMTP id m6S9U24l067794 for ; Mon, 28 Jul 2008 09:30:02 GMT (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.14.2/8.14.1/Submit) id m6S9U2Wr067793; Mon, 28 Jul 2008 09:30:02 GMT (envelope-from gnats) Resent-Date: Mon, 28 Jul 2008 09:30:02 GMT Resent-Message-Id: <200807280930.m6S9U2Wr067793@freefall.freebsd.org> Resent-From: FreeBSD-gnats-submit@FreeBSD.org (GNATS Filer) Resent-To: freebsd-doc@FreeBSD.org Resent-Reply-To: FreeBSD-gnats-submit@FreeBSD.org, Gavin Atkinson Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 1D63E106567B for ; Mon, 28 Jul 2008 09:27:07 +0000 (UTC) (envelope-from ga9@buffy.york.ac.uk) Received: from mail-gw2.york.ac.uk (mail-gw2.york.ac.uk [144.32.128.247]) by mx1.freebsd.org (Postfix) with ESMTP id BD80B8FC19 for ; Mon, 28 Jul 2008 09:27:06 +0000 (UTC) (envelope-from ga9@buffy.york.ac.uk) Received: from mail-gw6.york.ac.uk (mail-gw6.york.ac.uk [144.32.129.26]) by mail-gw2.york.ac.uk (8.13.6/8.13.6) with ESMTP id m6S9R2FP020528 for ; Mon, 28 Jul 2008 10:27:02 +0100 (BST) Received: from buffy-128.york.ac.uk ([144.32.128.160] helo=buffy.york.ac.uk) by mail-gw6.york.ac.uk with esmtps (TLSv1:AES256-SHA:256) (Exim 4.68) (envelope-from ) id 1KNP0Q-0003dl-Ja for FreeBSD-gnats-submit@freebsd.org; Mon, 28 Jul 2008 10:27:02 +0100 Received: from buffy.york.ac.uk (localhost [127.0.0.1]) by buffy.york.ac.uk (8.14.2/8.14.2) with ESMTP id m6S9R2oD063283 for ; Mon, 28 Jul 2008 10:27:02 +0100 (BST) (envelope-from ga9@buffy.york.ac.uk) Received: (from ga9@localhost) by buffy.york.ac.uk (8.14.2/8.14.2/Submit) id m6S9R2Hc063282; Mon, 28 Jul 2008 10:27:02 +0100 (BST) (envelope-from ga9) Message-Id: <200807280927.m6S9R2Hc063282@buffy.york.ac.uk> Date: Mon, 28 Jul 2008 10:27:02 +0100 (BST) From: Gavin Atkinson To: FreeBSD-gnats-submit@FreeBSD.org X-Send-Pr-Version: 3.113 Cc: Subject: docs/126030: [patch] updates to developers handbook: policies section X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list Reply-To: Gavin Atkinson List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 28 Jul 2008 09:30:02 -0000 >Number: 126030 >Category: docs >Synopsis: [patch] updates to developers handbook: policies section >Confidential: no >Severity: non-critical >Priority: low >Responsible: freebsd-doc >State: open >Quarter: >Keywords: >Date-Required: >Class: doc-bug >Submitter-Id: current-users >Arrival-Date: Mon Jul 28 09:30:01 UTC 2008 >Closed-Date: >Last-Modified: >Originator: Gavin Atkinson >Release: FreeBSD 7.0-STABLE amd64 >Organization: >Environment: System: FreeBSD buffy.york.ac.uk 7.0-STABLE FreeBSD 7.0-STABLE #3: Fri Jun 20 09:21:51 UTC 2008 root@buffy.york.ac.uk:/usr/obj/usr/src/sys/GENERIC amd64 >Description: The "policies" section of the developers-handbook is outdated, and doesn't document some recent and not-so-recent changes to FreeBSD: 1. The existence of src/MAINTAINERS is not mentioned 2. Add suggestion about how to identify possible maintainers, inspired by the committers-guide 3. Tcl has been removed from the base distribution, so doesn't really serve as a good example of contributed software any more (obsoletes docs/50735) 4. Mention the growing use of FREEBSD-Xlist files for contrib software 5. Clarify about shared library bumps. Note that this section really could do with mention and example of versioned libraries, I'm not able to contribute that. Also, somebody who knows how the CDDL fits with FreeBSD needs to update the "encumbered" section to either show that it is treated like GPL software, or that it isn't. Again, I've left that untouched as I don't know the answer. >How-To-Repeat: N/A >Fix: --- devh-policies.diff begins here --- Index: doc/en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml =================================================================== RCS file: /home/dcvs/doc/en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml,v retrieving revision 1.33 diff -u -r1.33 chapter.sgml --- doc/en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml 28 Feb 2007 18:21:29 -0000 1.33 +++ doc/en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml 28 Jul 2008 09:15:12 -0000 @@ -24,17 +24,26 @@ <makevar>MAINTAINER</makevar> on Makefiles ports maintainer - - If a particular portion of the FreeBSD distribution is being - maintained by a person or group of persons, they can communicate this - fact to the world by adding a + + If a particular portion of the FreeBSD src/ + distribution is being maintained by a person or group of persons, this + is communicated through an entry in the src/MAINTAINERS + file. + + Maintainers of ports within the Ports Collection express their + maintainership to the world by adding a MAINTAINER + line to the Makefile of the port in question: MAINTAINER= email-addresses - line to the Makefiles covering this portion of the - source tree. + - The semantics of this are as follows: + For other parts of the repository, or for sections not listed as + having a maintainer, if you are unsure who the active maintainer might + be it may help to scan the output of cvs log + to see who has committed changes in the past. + + The role of the maintainer is as follows: The maintainer owns and is responsible for that code. This means that he is responsible for fixing bugs and answering problem reports @@ -111,32 +120,27 @@ change can be rather dramatic. - The Tcl embedded programming - language will be used as example of how this model works: + The file utility, used to identify the format + of a file, will be used as example of how this model works: - src/contrib/tcl contains the source as + src/contrib/file contains the source as distributed by the maintainers of this package. Parts that are entirely - not applicable for FreeBSD can be removed. In the case of Tcl, the - mac, win and - compat subdirectories were eliminated before the - import. + not applicable for FreeBSD can be removed. In the case of &man.file.1;, the + python subdirectory and lt* files + were eliminated before the import, amongst others. - src/lib/libtcl contains only a bmake style + src/lib/libmagic contains only a bmake style Makefile that uses the standard bsd.lib.mk makefile rules to produce the library and install the documentation. - src/usr.bin/tclsh contains only a bmake style + src/usr.bin/file contains only a bmake style Makefile which will produce and install the - tclsh program and its associated man-pages using the + file program and its associated man-pages using the standard bsd.prog.mk rules. - src/tools/tools/tcl_bmake contains a couple of - shell-scripts that can be of help when the tcl software needs updating. - These are not part of the built or installed software. - The important thing here is that the - src/contrib/tcl directory is created according to + src/contrib/file directory is created according to the rules: it is supposed to contain the sources as distributed (on a proper CVS vendor-branch and without RCS keyword expansion) with as few FreeBSD-specific changes as possible. If there are any doubts on @@ -168,7 +172,7 @@ src/tools directory along with the port itself so that it is available to future maintainers. - In the src/contrib/tcl level directory, a file + In the src/contrib/file level directory, a file called FREEBSD-upgrade should be added and it should state things like: @@ -192,10 +196,8 @@ - However, please do not import FREEBSD-upgrade - with the contributed source. Rather you should cvs add - FREEBSD-upgrade ; cvs ci after the initial import. Example - wording from src/contrib/cpio is below: + Example wording from + src/contrib/cpio/FREEBSD-upgrade is below: This directory contains virgin sources of the original distribution files on a "vendor" branch. Do not, under any circumstances, attempt to upgrade @@ -235,6 +237,33 @@ inclusion in the next vendor release. obrien@FreeBSD.org - 30 March 1997 + + Another approach may also be taken for the list of files to be + excluded, which is especially useful when the list is large or + complicated or where imports happen frequently. By creating a file + FREEBSD-Xlist in the same directory the vendor source + is imported into, containing a list of filename patterns to be excluded one + per line, future imports can often be performed with: + + &prompt.user; tar -X FREEBSD-Xlist -xzf vendor-source.tgz + + + An example of a FREEBSD-Xlist file, from + src/contrib/tcsh, is here: + + */BUGS +*/config/a* +*/config/bs2000 +*/config/bsd +*/config/bsdreno +*/config/[c-z]* +*/tests +*/win32 + + However, please do not import FREEBSD-upgrade + or FREEBSD-Xlist with the contributed source. + Rather you should cvs add FREEBSD-upgrade FREEBSD-Xlist; + cvs ci after the initial import. @@ -409,9 +438,9 @@ based on the type of system. For non-port libraries, it is also our policy to change the shared - library version number only once between releases. In addition, it is + library version number at most once between releases. In addition, it is our policy to change the major shared library version number only once - between major OS releases (i.e. from 3.0 to 4.0). When you make a + between major OS releases (i.e. from 6.0 to 7.0). When you make a change to a system library that requires the version number to be bumped, check the Makefile's commit logs. It is the responsibility of the committer to ensure that the first such change --- devh-policies.diff ends here --- >Release-Note: >Audit-Trail: >Unformatted: