From owner-svn-doc-all@FreeBSD.ORG Wed Jul 24 03:00:29 2013 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) by hub.freebsd.org (Postfix) with ESMTP id D84CFC11; Wed, 24 Jul 2013 03:00:29 +0000 (UTC) (envelope-from wblock@FreeBSD.org) 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 C2C89239B; Wed, 24 Jul 2013 03:00:29 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.7/8.14.7) with ESMTP id r6O30Ter074758; Wed, 24 Jul 2013 03:00:29 GMT (envelope-from wblock@svn.freebsd.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.7/8.14.5/Submit) id r6O30Tsr074757; Wed, 24 Jul 2013 03:00:29 GMT (envelope-from wblock@svn.freebsd.org) Message-Id: <201307240300.r6O30Tsr074757@svn.freebsd.org> From: Warren Block Date: Wed, 24 Jul 2013 03:00:29 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r42408 - head/en_US.ISO8859-1/books/developers-handbook/policies X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 24 Jul 2013 03:00:29 -0000 Author: wblock Date: Wed Jul 24 03:00:29 2013 New Revision: 42408 URL: http://svnweb.freebsd.org/changeset/doc/42408 Log: Whitespace-only fixes. Translators, please ignore. Modified: head/en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml Modified: head/en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml Wed Jul 24 02:39:59 2013 (r42407) +++ head/en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml Wed Jul 24 03:00:29 2013 (r42408) @@ -13,7 +13,7 @@ Kamp Contributed by - + Giorgos Keramidas @@ -23,70 +23,76 @@ Source Tree Guidelines and Policies - This chapter documents various guidelines and policies in force for - the FreeBSD source tree. + This chapter documents various guidelines and policies in + force for the FreeBSD source tree. Style Guidelines + style Consistent coding style is extremely important, particularly - with large projects like &os;. Code should follow the &os; coding - styles described in &man.style.9; and + with large projects like &os;. Code should follow the &os; + coding styles described in &man.style.9; and &man.style.Makefile.5;. <makevar>MAINTAINER</makevar> on Makefiles + ports maintainer - If a particular portion of the &os; 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 + If a particular portion of the &os; + 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 - For other parts of the repository, or for sections not listed - as having a maintainer, or when you are unsure who the active - maintainer is, try looking at the recent commit history of the - relevant parts of the source tree. It is quite often the case - that a maintainer is not explicitly named, but the people who are - actively working in a part of the source tree for, say, the last - couple of years are interested in reviewing changes. Even if this - is not specifically mentioned in the documentation or the source - itself, asking for a review as a form of courtesy is a very - reasonable thing to do. + For other parts of the repository, or for sections not + listed as having a maintainer, or when you are unsure who the + active maintainer is, try looking at the recent commit history + of the relevant parts of the source tree. It is quite often + the case that a maintainer is not explicitly named, but the + people who are actively working in a part of the source tree + for, say, the last couple of years are interested in reviewing + changes. Even if this is not specifically mentioned in the + documentation or the source itself, asking for a review as a + form of courtesy is a very reasonable thing to do. The role of the maintainer is as follows: - The maintainer owns and is responsible for that code. This means - that he or she is responsible for fixing bugs and answering problem reports - pertaining to that piece of the code, and in the case of contributed - software, for tracking new versions, as appropriate. + The maintainer owns and is responsible for that code. + This means that he or she is responsible for fixing bugs and + answering problem reports pertaining to that piece of the + code, and in the case of contributed software, for tracking + new versions, as appropriate. - Changes to directories which have a maintainer defined shall be sent - to the maintainer for review before being committed. Only if the - maintainer does not respond for an unacceptable period of time, to - several emails, will it be acceptable to commit changes without review - by the maintainer. However, it is suggested that you try to have the - changes reviewed by someone else if at all possible. + Changes to directories which have a maintainer defined + shall be sent to the maintainer for review before being + committed. Only if the maintainer does not respond for an + unacceptable period of time, to several emails, will it be + acceptable to commit changes without review by the + maintainer. However, it is suggested that you try to have + the changes reviewed by someone else if at all + possible. - It is of course not acceptable to add a person or group as - maintainer unless they agree to assume this duty. On the other hand it - does not have to be a committer and it can easily be a group of - people. + It is of course not acceptable to add a person or group + as maintainer unless they agree to assume this duty. On the + other hand it does not have to be a committer and it can + easily be a group of people. @@ -115,37 +121,44 @@ contributed software - Some parts of the FreeBSD distribution consist of software that is - actively being maintained outside the FreeBSD project. For historical - reasons, we call this contributed software. Some - examples are sendmail, gcc and patch. - - Over the last couple of years, various methods have been used in - dealing with this type of software and all have some number of - advantages and drawbacks. No clear winner has emerged. - - Since this is the case, after some debate one of these methods has - been selected as the official method and will be required - for future imports of software of this kind. Furthermore, it is - strongly suggested that existing contributed software converge on this - model over time, as it has significant advantages over the old method, - including the ability to easily obtain diffs relative to the - official versions of the source by everyone (even without - direct repository access). This will make it significantly easier to return changes - to the primary developers of the contributed software. - - Ultimately, however, it comes down to the people actually doing the - work. If using this model is particularly unsuited to the package being - dealt with, exceptions to these rules may be granted only with the - approval of the core team and with the general consensus of the other - developers. The ability to maintain the package in the future will be a - key issue in the decisions. + Some parts of the FreeBSD distribution consist of software + that is actively being maintained outside the FreeBSD project. + For historical reasons, we call this + contributed software. Some examples are + sendmail, + gcc and + patch. + + Over the last couple of years, various methods have been + used in dealing with this type of software and all have some + number of advantages and drawbacks. No clear winner has + emerged. + + Since this is the case, after some debate one of these + methods has been selected as the official method + and will be required for future imports of software of this + kind. Furthermore, it is strongly suggested that existing + contributed software converge on this model over time, as it has + significant advantages over the old method, including the + ability to easily obtain diffs relative to the + official versions of the source by everyone (even + without direct repository access). This will make it + significantly easier to return changes to the primary developers + of the contributed software. + + Ultimately, however, it comes down to the people actually + doing the work. If using this model is particularly unsuited to + the package being dealt with, exceptions to these rules may be + granted only with the approval of the core team and with the + general consensus of the other developers. The ability to + maintain the package in the future will be a key issue in the + decisions. Because it makes it harder to import future versions - minor, trivial and/or - cosmetic changes are strongly discouraged on - files that are still tracking the vendor branch. + minor, trivial and/or cosmetic changes are + strongly discouraged on files that are + still tracking the vendor branch. @@ -169,16 +182,16 @@ If this is your first import after the switch to SVN, you will have to flatten and clean - up the vendor tree, and bootstrap merge history in the main - tree. If not, you can safely omit this step. + up the vendor tree, and bootstrap merge history in the + main tree. If not, you can safely omit this step. During the conversion from CVS to SVN, vendor branches were imported with the same layout as the main tree. For example, the foo vendor sources ended up in vendor/foo/dist/contrib/foo, - but it is pointless and rather inconvenient. What we really - want is to have the vendor source directly in + but it is pointless and rather inconvenient. What we + really want is to have the vendor source directly in vendor/foo/dist, like this: @@ -192,9 +205,9 @@ Note that, the propdel bit is necessary because starting with 1.5, Subversion will automatically add svn:mergeinfo to any - directory you copy or move. In this case, you will not need - this information, since you are not going to merge anything - from the tree you deleted. + directory you copy or move. In this case, you will not + need this information, since you are not going to merge + anything from the tree you deleted. You may want to flatten the tags as well. The @@ -202,19 +215,19 @@ the commit until the end. - Check the dist tree and perform any - cleanup that is deemed to be necessary. You may want to - disable keyword expansion, as it makes no sense on + Check the dist tree and perform + any cleanup that is deemed to be necessary. You may want + to disable keyword expansion, as it makes no sense on unmodified vendor code. In some cases, it can be even be harmful. &prompt.user; svn propdel svn:keywords . &prompt.user; svn commit - Bootstrapping of svn:mergeinfo on the - target directory (in the main tree) to the revision that - corresponds to the last change was made to the vendor tree - prior to importing new sources is also needed: + Bootstrapping of svn:mergeinfo on + the target directory (in the main tree) to the revision + that corresponds to the last change was made to the vendor + tree prior to importing new sources is also needed: &prompt.user; cd head/contrib/foo &prompt.user; svn merge svn_base/vendor/foo/dist@12345678 . @@ -228,16 +241,17 @@ Importing New Sources - Prepare a full, clean tree of the vendor sources. With - SVN, we can keep a full distribution in - the vendor tree without bloating the main tree. Import - everything but merge only what is needed. - - Note that you will need to add any files that were added - since the last vendor import, and remove any that were - removed. To facilitate this, you should prepare sorted - lists of the contents of the vendor tree and of the sources - you are about to import: + Prepare a full, clean tree of the vendor sources. + With SVN, we can keep a full + distribution in the vendor tree without bloating the main + tree. Import everything but merge only what is + needed. + + Note that you will need to add any files that were + added since the last vendor import, and remove any that + were removed. To facilitate this, you should prepare + sorted lists of the contents of the vendor tree and of the + sources you are about to import: &prompt.user; cd vendor/foo/dist &prompt.user; svn list | grep '/$' | sort > ../old @@ -265,11 +279,11 @@ &prompt.user; comm ../old ../new | xargs svn add - If there are new directories in the new distribution, - the last command will fail. You will have to add the - directories, and run it again. Conversely, if any - directories were removed, you will have to remove them - manually. + If there are new directories in the new + distribution, the last command will fail. You will have + to add the directories, and run it again. Conversely, + if any directories were removed, you will have to remove + them manually. Check properties on any new files: @@ -302,8 +316,9 @@ You are ready to commit, but you should first check - the output of svn stat and svn - diff to make sure everything is in order. + the output of svn stat and + svn diff to make sure everything is + in order. Once you have committed the new vendor release, you @@ -312,12 +327,13 @@ &prompt.user; svn copy svn_base/vendor/foo/dist svn_base/vendor/foo/9.9 - To get the new tag, you can update your working copy of + To get the new tag, you can update your working copy + of vendor/foo. - If you choose to do the copy in the checkout instead, - do not forget to remove the generated + If you choose to do the copy in the checkout + instead, do not forget to remove the generated svn:mergeinfo as described above. @@ -335,10 +351,11 @@ &prompt.user; svn update &prompt.user; svn merge svn_base/vendor/foo/dist - Resolve any conflicts, and make sure that any files that - were added or removed in the vendor tree have been properly - added or removed in the main tree. It is always a good idea - to check differences against the vendor branch: + Resolve any conflicts, and make sure that any files + that were added or removed in the vendor tree have been + properly added or removed in the main tree. It is always + a good idea to check differences against the vendor + branch: &prompt.user; svn diff svn_base/vendor/foo/dist . @@ -347,16 +364,16 @@ vendor tree but not in the main tree. - With SVN, there is no concept of on - or off the vendor branch. If a file that previously had - local modifications no longer does, just remove any + With SVN, there is no concept of + on or off the vendor branch. If a file that previously + had local modifications no longer does, just remove any left-over cruft, such as &os; version tags, so it no longer shows up in diffs against the vendor tree. - If any changes are required for the world to build with - the new sources, make them now — and test until you - are satisfied that everything build and runs + If any changes are required for the world to build + with the new sources, make them now — and test until + you are satisfied that everything build and runs correctly. @@ -378,93 +395,103 @@ Encumbered Files - It might occasionally be necessary to include an encumbered file in - the FreeBSD source tree. For example, if a device requires a small - piece of binary code to be loaded to it before the device will operate, - and we do not have the source to that code, then the binary file is said - to be encumbered. The following policies apply to including encumbered - files in the FreeBSD source tree. + It might occasionally be necessary to include an encumbered + file in the FreeBSD source tree. For example, if a device + requires a small piece of binary code to be loaded to it before + the device will operate, and we do not have the source to that + code, then the binary file is said to be encumbered. The + following policies apply to including encumbered files in the + FreeBSD source tree. - Any file which is interpreted or executed by the system CPU(s) - and not in source format is encumbered. + Any file which is interpreted or executed by the system + CPU(s) and not in source format is encumbered. - Any file with a license more restrictive than BSD or GNU is - encumbered. + Any file with a license more restrictive than BSD or GNU + is encumbered. - A file which contains downloadable binary data for use by the - hardware is not encumbered, unless (1) or (2) apply to it. It must - be stored in an architecture neutral ASCII format (file2c or - uuencoding is recommended). + A file which contains downloadable binary data for use + by the hardware is not encumbered, unless (1) or (2) apply + to it. It must be stored in an architecture neutral ASCII + format (file2c or uuencoding is recommended). - Any encumbered file requires specific approval from the - Core Team before it is added to the - repository. + Any encumbered file requires specific approval from the + Core + Team before it is added to the repository. - Encumbered files go in src/contrib or - src/sys/contrib. + Encumbered files go in src/contrib + or src/sys/contrib. - The entire module should be kept together. There is no point in - splitting it, unless there is code-sharing with non-encumbered - code. + The entire module should be kept together. There is no + point in splitting it, unless there is code-sharing with + non-encumbered code. - Object files are named + Object files are named arch/filename.o.uu>. - Kernel files: + Kernel files: - - - Should always be referenced in - conf/files.* (for build simplicity). + + + Should always be referenced in + conf/files.* (for build + simplicity). - - Should always be in LINT, but the - Core Team decides per case if it - should be commented out or not. The - Core Team can, of course, change - their minds later on. - - - - The Release Engineer - decides whether or not it goes into the release. - - + + Should always be in LINT, but + the Core + Team decides per case if it should be + commented out or not. The Core + Team can, of course, change their minds later + on. + + + + The Release Engineer + decides whether or not it goes into the release. + + - User-land files: - - - - The Core team - core team decides if - the code should be part of make world. - - - - The Release Engineering - release engineering - decides if it goes into the release. - - + User-land files: + + + + The Core + teamcore + team decides if + the code should be part of + make world. + + + + The Release + Engineeringrelease + engineering + decides if it goes into the release. + + @@ -491,10 +518,11 @@ Shared Libraries - If you are adding shared library support to a port or other piece of - software that does not have one, the version numbers should follow these - rules. Generally, the resulting numbers will have nothing to do with - the release version of the software. + If you are adding shared library support to a port or other + piece of software that does not have one, the version numbers + should follow these rules. Generally, the resulting numbers + will have nothing to do with the release version of the + software. The three principles of shared library building are: @@ -504,57 +532,64 @@ - If there is a change that is backwards compatible, bump minor - number (note that ELF systems ignore the minor number) + If there is a change that is backwards compatible, bump + minor number (note that ELF systems ignore the minor + number) - If there is an incompatible change, bump major number + If there is an incompatible change, bump major + number - For instance, added functions and bugfixes result in the minor - version number being bumped, while deleted functions, changed function - call syntax, etc. will force the major version number to change. + For instance, added functions and bugfixes result in the + minor version number being bumped, while deleted functions, + changed function call syntax, etc. will force the major version + number to change. Stick to version numbers of the form major.minor - (x.y). Our a.out - dynamic linker does not handle version numbers of the form + (x.y). + Our a.out dynamic linker does not handle version numbers of the + form x.y.z well. Any version number after the y - (i.e. the third digit) is totally ignored when comparing shared lib - version numbers to decide which library to link with. Given two shared - libraries that differ only in the micro revision, - ld.so will link with the higher one. That is, if you link - with libfoo.so.3.3.3, the linker only records - 3.3 in the headers, and will link with anything - starting with - libfoo.so.3.(anything >= - 3).(highest + (i.e. the third digit) is totally ignored when comparing shared + lib version numbers to decide which library to link with. Given + two shared libraries that differ only in the + micro revision, ld.so will + link with the higher one. That is, if you link with + libfoo.so.3.3.3, the linker only records + 3.3 in the headers, and will link with + anything starting with + libfoo.so.3.(anything + >= 3).(highest available). ld.so will always use the highest minor revision. For instance, it will use libc.so.2.2 in preference to - libc.so.2.0, even if the program was initially - linked with libc.so.2.0. + libc.so.2.0, even if the program was + initially linked with libc.so.2.0. - In addition, our ELF dynamic linker does not handle minor version - numbers at all. However, one should still specify a major and minor - version number as our Makefiles do the right thing - 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 - our policy to change the major shared library version number only once - 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 - since the release will result in the shared library version number in - the Makefile to be updated, and any subsequent - changes will not. + In addition, our ELF dynamic linker does not handle minor + version numbers at all. However, one should still specify a + major and minor version number as our + Makefiles do the right thing + 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 our policy to change the major shared library + version number only once 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 since the release will result in the shared library + version number in the Makefile to be + updated, and any subsequent changes will not.