Date: Wed, 24 Jul 2013 03:00:29 +0000 (UTC) From: Warren Block <wblock@FreeBSD.org> 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 Message-ID: <201307240300.r6O30Tsr074757@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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 @@ <surname>Kamp</surname> <contrib>Contributed by </contrib> </author> - <author> + <author> <firstname>Giorgos</firstname> <surname>Keramidas</surname> </author> @@ -23,70 +23,76 @@ <title>Source Tree Guidelines and Policies</title> - <para>This chapter documents various guidelines and policies in force for - the FreeBSD source tree.</para> + <para>This chapter documents various guidelines and policies in + force for the FreeBSD source tree.</para> <sect1 id="policies-style"> <title>Style Guidelines</title> + <indexterm><primary>style</primary></indexterm> <para>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;.</para> </sect1> <sect1 id="policies-maintainer"> <title><makevar>MAINTAINER</makevar> on Makefiles</title> + <indexterm><primary>ports maintainer</primary></indexterm> - <para>If a particular portion of the &os; <filename>src/</filename> - distribution is being maintained by a person or group of persons, - this is communicated through an entry in the - <filename>src/MAINTAINERS</filename> file. Maintainers of ports - within the Ports Collection express their maintainership to the - world by adding a <makevar>MAINTAINER</makevar> line to the + <para>If a particular portion of the &os; + <filename>src/</filename> distribution is being maintained by a + person or group of persons, this is communicated through an + entry in the <filename>src/MAINTAINERS</filename> file. + Maintainers of ports within the Ports Collection express their + maintainership to the world by adding a + <makevar>MAINTAINER</makevar> line to the <filename>Makefile</filename> of the port in question:</para> <programlisting><makevar>MAINTAINER</makevar>= <replaceable>email-addresses</replaceable></programlisting> <tip> - <para>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.</para> + <para>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.</para> </tip> <para>The role of the maintainer is as follows:</para> <itemizedlist> <listitem> - <para>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.</para> + <para>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.</para> </listitem> <listitem> - <para>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.</para> + <para>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.</para> </listitem> <listitem> - <para>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.</para> + <para>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.</para> </listitem> </itemizedlist> </sect1> @@ -115,37 +121,44 @@ <indexterm><primary>contributed software</primary></indexterm> - <para>Some parts of the FreeBSD distribution consist of software that is - actively being maintained outside the FreeBSD project. For historical - reasons, we call this <emphasis>contributed</emphasis> software. Some - examples are <application>sendmail</application>, <application>gcc</application> and <application>patch</application>.</para> - - <para>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.</para> - - <para>Since this is the case, after some debate one of these methods has - been selected as the <quote>official</quote> 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 - <quote>official</quote> 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.</para> - - <para>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.</para> + <para>Some parts of the FreeBSD distribution consist of software + that is actively being maintained outside the FreeBSD project. + For historical reasons, we call this + <emphasis>contributed</emphasis> software. Some examples are + <application>sendmail</application>, + <application>gcc</application> and + <application>patch</application>.</para> + + <para>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.</para> + + <para>Since this is the case, after some debate one of these + methods has been selected as the <quote>official</quote> 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 + <quote>official</quote> 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.</para> + + <para>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.</para> <note> <para>Because it makes it harder to import future versions - minor, trivial and/or - cosmetic changes are <emphasis>strongly discouraged</emphasis> on - files that are still tracking the vendor branch.</para> + minor, trivial and/or cosmetic changes are + <emphasis>strongly discouraged</emphasis> on files that are + still tracking the vendor branch.</para> </note> <sect2 id="vendor-import-svn"> @@ -169,16 +182,16 @@ <para>If this is your first import after the switch to <acronym>SVN</acronym>, 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.</para> + up the vendor tree, and bootstrap merge history in the + main tree. If not, you can safely omit this step.</para> <para>During the conversion from <acronym>CVS</acronym> to <acronym>SVN</acronym>, vendor branches were imported with the same layout as the main tree. For example, the <application>foo</application> vendor sources ended up in <filename>vendor/<replaceable>foo</replaceable>/dist/contrib/<replaceable>foo</replaceable></filename>, - 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 <filename>vendor/<replaceable>foo</replaceable>/dist</filename>, like this:</para> @@ -192,9 +205,9 @@ <para>Note that, the <literal>propdel</literal> bit is necessary because starting with 1.5, Subversion will automatically add <literal>svn:mergeinfo</literal> 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.</para> + 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.</para> <note> <para>You may want to flatten the tags as well. The @@ -202,19 +215,19 @@ the commit until the end.</para> </note> - <para>Check the <filename>dist</filename> tree and perform any - cleanup that is deemed to be necessary. You may want to - disable keyword expansion, as it makes no sense on + <para>Check the <filename>dist</filename> 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.</para> <screen>&prompt.user; <userinput><command>svn propdel</command> svn:keywords <option>-R</option> <filename>.</filename></userinput> &prompt.user; <userinput><command>svn commit</command></userinput></screen> - <para>Bootstrapping of <literal>svn:mergeinfo</literal> 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:</para> + <para>Bootstrapping of <literal>svn:mergeinfo</literal> 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:</para> <screen>&prompt.user; <userinput><command>cd</command> <filename>head/contrib/<replaceable>foo</replaceable></filename></userinput> &prompt.user; <userinput><command>svn merge</command> <option>--record-only</option> <replaceable>svn_base</replaceable>/vendor/<replaceable>foo</replaceable>/dist@<replaceable>12345678</replaceable> <filename>.</filename></userinput> @@ -228,16 +241,17 @@ <step> <title>Importing New Sources</title> - <para>Prepare a full, clean tree of the vendor sources. With - <acronym>SVN</acronym>, we can keep a full distribution in - the vendor tree without bloating the main tree. Import - everything but merge only what is needed.</para> - - <para>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:</para> + <para>Prepare a full, clean tree of the vendor sources. + With <acronym>SVN</acronym>, we can keep a full + distribution in the vendor tree without bloating the main + tree. Import everything but merge only what is + needed.</para> + + <para>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:</para> <screen>&prompt.user; <userinput><command>cd</command> <filename>vendor/<replaceable>foo</replaceable>/dist</filename></userinput> &prompt.user; <userinput><command>svn list</command> <option>-R</option> | <command>grep</command> <option>-v</option> '/$' | <command>sort</command> > <filename>../<replaceable>old</replaceable></filename></userinput> @@ -265,11 +279,11 @@ &prompt.user; <userinput><command>comm</command> <option>-13</option> <filename>../<replaceable>old</replaceable></filename> <filename>../<replaceable>new</replaceable></filename> | <command>xargs</command> svn add</userinput></screen> <warning> - <para>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.</para> + <para>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.</para> </warning> <para>Check properties on any new files:</para> @@ -302,8 +316,9 @@ <note> <para>You are ready to commit, but you should first check - the output of <command>svn stat</command> and <command>svn - diff</command> to make sure everything is in order.</para> + the output of <command>svn stat</command> and + <command>svn diff</command> to make sure everything is + in order.</para> </note> <para>Once you have committed the new vendor release, you @@ -312,12 +327,13 @@ <screen>&prompt.user; <userinput><command>svn copy</command> <filename><replaceable>svn_base</replaceable>/vendor/<replaceable>foo</replaceable>/dist</filename> <filename><replaceable>svn_base</replaceable>/vendor/<replaceable>foo</replaceable>/<replaceable>9.9</replaceable></filename></userinput></screen> - <para>To get the new tag, you can update your working copy of + <para>To get the new tag, you can update your working copy + of <filename>vendor/<replaceable>foo</replaceable></filename>.</para> <note> - <para>If you choose to do the copy in the checkout instead, - do not forget to remove the generated + <para>If you choose to do the copy in the checkout + instead, do not forget to remove the generated <literal>svn:mergeinfo</literal> as described above.</para> </note> @@ -335,10 +351,11 @@ &prompt.user; <userinput><command>svn update</command></userinput> &prompt.user; <userinput><command>svn merge</command> <option>--accept=postpone</option> <filename><replaceable>svn_base</replaceable>/vendor/<replaceable>foo</replaceable>/dist</filename></userinput></screen> - <para>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:</para> + <para>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:</para> <screen>&prompt.user; <userinput><command>svn diff</command> <option>--no-diff-deleted</option> <option>--old=</option><filename><replaceable>svn_base</replaceable>/vendor/<replaceable>foo</replaceable>/dist</filename> <option>--new=</option><filename>.</filename></userinput></screen> @@ -347,16 +364,16 @@ vendor tree but not in the main tree.</para> <note> - <para>With <acronym>SVN</acronym>, 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 + <para>With <acronym>SVN</acronym>, 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.</para> </note> - <para>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 + <para>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.</para> </step> @@ -378,93 +395,103 @@ <sect1 id="policies-encumbered"> <title>Encumbered Files</title> - <para>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.</para> + <para>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.</para> <orderedlist> <listitem> - <para>Any file which is interpreted or executed by the system CPU(s) - and not in source format is encumbered.</para> + <para>Any file which is interpreted or executed by the system + CPU(s) and not in source format is encumbered.</para> </listitem> <listitem> - <para>Any file with a license more restrictive than BSD or GNU is - encumbered.</para> + <para>Any file with a license more restrictive than BSD or GNU + is encumbered.</para> </listitem> <listitem> - <para>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).</para> + <para>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).</para> </listitem> <listitem> - <para>Any encumbered file requires specific approval from the - <ulink url="&url.base;/administration.html#t-core">Core Team</ulink> before it is added to the - repository.</para> + <para>Any encumbered file requires specific approval from the + <ulink url="&url.base;/administration.html#t-core">Core + Team</ulink> before it is added to the repository.</para> </listitem> <listitem> - <para>Encumbered files go in <filename>src/contrib</filename> or - <filename>src/sys/contrib</filename>.</para> + <para>Encumbered files go in <filename>src/contrib</filename> + or <filename>src/sys/contrib</filename>.</para> </listitem> <listitem> - <para>The entire module should be kept together. There is no point in - splitting it, unless there is code-sharing with non-encumbered - code.</para> + <para>The entire module should be kept together. There is no + point in splitting it, unless there is code-sharing with + non-encumbered code.</para> </listitem> <listitem> - <para>Object files are named + <para>Object files are named <filename><replaceable>arch</replaceable>/<replaceable>filename</replaceable>.o.uu></filename>.</para> </listitem> <listitem> - <para>Kernel files:</para> + <para>Kernel files:</para> - <orderedlist> - <listitem> - <para>Should always be referenced in - <filename>conf/files.*</filename> (for build simplicity).</para> + <orderedlist> + <listitem> + <para>Should always be referenced in + <filename>conf/files.*</filename> (for build + simplicity).</para> </listitem> - <listitem> - <para>Should always be in <filename>LINT</filename>, but the - <ulink url="&url.base;/administration.html#t-core">Core Team</ulink> decides per case if it - should be commented out or not. The - <ulink url="&url.base;/administration.html#t-core">Core Team</ulink> can, of course, change - their minds later on.</para> - </listitem> - - <listitem> - <para>The <firstterm>Release Engineer</firstterm> - decides whether or not it goes into the release.</para> - </listitem> - </orderedlist> + <listitem> + <para>Should always be in <filename>LINT</filename>, but + the <ulink + url="&url.base;/administration.html#t-core">Core + Team</ulink> decides per case if it should be + commented out or not. The <ulink + url="&url.base;/administration.html#t-core">Core + Team</ulink> can, of course, change their minds later + on.</para> + </listitem> + + <listitem> + <para>The <firstterm>Release Engineer</firstterm> + decides whether or not it goes into the release.</para> + </listitem> + </orderedlist> </listitem> <listitem> - <para>User-land files:</para> - - <orderedlist> - <listitem> - <para>The <ulink url="&url.base;/administration.html#t-core">Core team</ulink><indexterm> - <primary>core team</primary></indexterm> decides if - the code should be part of <command>make world</command>.</para> - </listitem> - - <listitem> - <para>The <ulink url="&url.base;/administration.html#t-re">Release Engineering</ulink><indexterm> - <primary>release engineering</primary></indexterm> - decides if it goes into the release.</para> - </listitem> - </orderedlist> + <para>User-land files:</para> + + <orderedlist> + <listitem> + <para>The <ulink + url="&url.base;/administration.html#t-core">Core + team</ulink><indexterm><primary>core + team</primary></indexterm> decides if + the code should be part of + <command>make world</command>.</para> + </listitem> + + <listitem> + <para>The <ulink + url="&url.base;/administration.html#t-re">Release + Engineering</ulink><indexterm><primary>release + engineering</primary></indexterm> + decides if it goes into the release.</para> + </listitem> + </orderedlist> </listitem> </orderedlist> </sect1> @@ -491,10 +518,11 @@ <title>Shared Libraries</title> - <para>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.</para> + <para>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.</para> <para>The three principles of shared library building are:</para> @@ -504,57 +532,64 @@ </listitem> <listitem> - <para>If there is a change that is backwards compatible, bump minor - number (note that ELF systems ignore the minor number)</para> + <para>If there is a change that is backwards compatible, bump + minor number (note that ELF systems ignore the minor + number)</para> </listitem> <listitem> - <para>If there is an incompatible change, bump major number</para> + <para>If there is an incompatible change, bump major + number</para> </listitem> </itemizedlist> - <para>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.</para> + <para>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.</para> <para>Stick to version numbers of the form major.minor - (<replaceable>x</replaceable>.<replaceable>y</replaceable>). Our a.out - dynamic linker does not handle version numbers of the form + (<replaceable>x</replaceable>.<replaceable>y</replaceable>). + Our a.out dynamic linker does not handle version numbers of the + form <replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable> well. Any version number after the <replaceable>y</replaceable> - (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 <quote>micro</quote> revision, - <command>ld.so</command> will link with the higher one. That is, if you link - with <filename>libfoo.so.3.3.3</filename>, the linker only records - <literal>3.3</literal> in the headers, and will link with anything - starting with - <replaceable>libfoo.so.3</replaceable>.<replaceable>(anything >= - 3)</replaceable>.<replaceable>(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 + <quote>micro</quote> revision, <command>ld.so</command> will + link with the higher one. That is, if you link with + <filename>libfoo.so.3.3.3</filename>, the linker only records + <literal>3.3</literal> in the headers, and will link with + anything starting with + <replaceable>libfoo.so.3</replaceable>.<replaceable>(anything + >= 3)</replaceable>.<replaceable>(highest available)</replaceable>.</para> <note> <para><command>ld.so</command> will always use the highest <quote>minor</quote> revision. For instance, it will use <filename>libc.so.2.2</filename> in preference to - <filename>libc.so.2.0</filename>, even if the program was initially - linked with <filename>libc.so.2.0</filename>.</para> + <filename>libc.so.2.0</filename>, even if the program was + initially linked with <filename>libc.so.2.0</filename>.</para> </note> - <para>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 <filename>Makefile</filename>s <quote>do the right thing</quote> - based on the type of system.</para> - - <para>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 <filename>Makefile</filename>'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 <filename>Makefile</filename> to be updated, and any subsequent - changes will not.</para> + <para>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 + <filename>Makefile</filename>s <quote>do the right thing</quote> + based on the type of system.</para> + + <para>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 + <filename>Makefile</filename>'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 <filename>Makefile</filename> to be + updated, and any subsequent changes will not.</para> </sect1> </chapter>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201307240300.r6O30Tsr074757>