git: 1cdbcb161b - main - Fix typos, style and fix AsciiDoc syntax in bsdl-gpl, building products and committers guide
Sergio Carlavilla Delgado
carlavilla at FreeBSD.org
Fri Mar 19 14:05:15 UTC 2021
The branch main has been updated by carlavilla:
URL: https://cgit.FreeBSD.org/doc/commit/?id=1cdbcb161b5f002a21212e0d7d1992d298898fcd
commit 1cdbcb161b5f002a21212e0d7d1992d298898fcd
Author: Sergio Carlavilla Delgado <carlavilla at FreeBSD.org>
AuthorDate: 2021-03-19 14:01:14 +0000
Commit: Sergio Carlavilla Delgado <carlavilla at FreeBSD.org>
CommitDate: 2021-03-19 14:01:14 +0000
Fix typos, style and fix AsciiDoc syntax in bsdl-gpl, building products and committers guide
bsdl-gpl: style line
building products: style line and fix images path
committers-guide: style line, convert some MarkDown
links to Asciidoc and upgrade some entries still making
reference to the old Docbook tech.
---
.../content/en/articles/bsdl-gpl/_index.adoc | 202 ++-
.../en/articles/building-products/_index.adoc | 118 +-
.../en/articles/committers-guide/_index.adoc | 1426 ++++++++++++--------
3 files changed, 1100 insertions(+), 646 deletions(-)
diff --git a/documentation/content/en/articles/bsdl-gpl/_index.adoc b/documentation/content/en/articles/bsdl-gpl/_index.adoc
index 6ee939f367..01b9cbebec 100644
--- a/documentation/content/en/articles/bsdl-gpl/_index.adoc
+++ b/documentation/content/en/articles/bsdl-gpl/_index.adoc
@@ -24,53 +24,102 @@ toc::[]
[[intro]]
== Introduction
-This document makes a case for using a BSD style license for software and data; specifically it recommends using a BSD style license in place of the GPL. It can also be read as a BSD versus GPL Open Source License introduction and summary.
+This document makes a case for using a BSD style license for software and data;
+specifically it recommends using a BSD style license in place of the GPL.
+It can also be read as a BSD versus GPL Open Source License introduction and summary.
[[history]]
== Very Brief Open Source History
-Long before the term "Open Source" was used, software was developed by loose associations of programmers and freely exchanged. Starting in the early 1950's, organizations such as http://www.share.org[SHARE] and http://www.decus.org[DECUS] developed much of the software that computer hardware companies bundled with their hardware offerings. At that time computer companies were in the hardware business; anything that reduced software cost and made more programs available made the hardware companies more competitive.
+Long before the term "Open Source" was used, software was developed by loose associations of programmers and freely exchanged.
+Starting in the early 1950's, organizations such as http://www.share.org[SHARE] and http://www.decus.org[DECUS] developed much of the software that computer hardware companies bundled with their hardware offerings.
+At that time computer companies were in the hardware business;
+anything that reduced software cost and made more programs available made the hardware companies more competitive.
-This model changed in the 1960's. In 1965 ADR developed the first licensed software product independent of a hardware company. ADR was competing against a free IBM package originally developed by IBM customers. ADR patented their software in 1968. To stop sharing of their program, they provided it under an equipment lease in which payment was spread over the lifetime of the product. ADR thus retained ownership and could control resale and reuse.
+This model changed in the 1960's.
+In 1965 ADR developed the first licensed software product independent of a hardware company.
+ADR was competing against a free IBM package originally developed by IBM customers.
+ADR patented their software in 1968.
+To stop sharing of their program, they provided it under an equipment lease in which payment was spread over the lifetime of the product.
+ADR thus retained ownership and could control resale and reuse.
-In 1969 the US Department of Justice charged IBM with destroying businesses by bundling free software with IBM hardware. As a result of this suit, IBM unbundled its software; that is, software became independent products separate from hardware.
+In 1969 the US Department of Justice charged IBM with destroying businesses by bundling free software with IBM hardware.
+As a result of this suit, IBM unbundled its software; that is, software became independent products separate from hardware.
-In 1968 Informatics introduced the first commercial killer-app and rapidly established the concept of the software product, the software company, and very high rates of return. Informatics developed the perpetual license which is now standard throughout the computer industry, wherein ownership is never transferred to the customer.
+In 1968 Informatics introduced the first commercial killer-app and rapidly established the concept of the software product,
+the software company, and very high rates of return.
+Informatics developed the perpetual license which is now standard throughout the computer industry,
+wherein ownership is never transferred to the customer.
[[unix-license]]
== Unix from a BSD Licensing Perspective
-AT&T, who owned the original Unix implementation, was a publicly regulated monopoly tied up in anti-trust court; it was legally unable to sell a product into the software market. It was, however, able to provide it to academic institutions for the price of media.
+AT&T, who owned the original Unix implementation,
+was a publicly regulated monopoly tied up in anti-trust court;
+it was legally unable to sell a product into the software market.
+It was, however, able to provide it to academic institutions for the price of media.
-Universities rapidly adopted Unix after an OS conference publicized its availability. It was extremely helpful that Unix ran on the PDP-11, a very affordable 16-bit computer, and was coded in a high-level language that was demonstrably good for systems programming. The DEC PDP-11 had, in effect, an open hardware interface designed to make it easy for customers to write their own OS, which was common. As DEC founder Ken Olsen famously proclaimed, "software comes from heaven when you have good hardware".
+Universities rapidly adopted Unix after an OS conference publicized its availability.
+It was extremely helpful that Unix ran on the PDP-11, a very affordable 16-bit computer,
+and was coded in a high-level language that was demonstrably good for systems programming.
+The DEC PDP-11 had, in effect, an open hardware interface designed to make it easy for customers to write their own OS, which was common.
+As DEC founder Ken Olsen famously proclaimed, "software comes from heaven when you have good hardware".
-Unix author Ken Thompson returned to his alma mater, University of California Berkeley (UCB), in 1975 and taught the kernel line-by-line. This ultimately resulted in an evolving system known as BSD (Berkeley Standard Distribution). UCB converted Unix to 32-bits, added virtual memory, and implemented the version of the TCP/IP stack upon which the Internet was essentially built. UCB made BSD available for the cost of media, under what became known as "the BSD license". A customer purchased Unix from AT&T and then ordered a BSD tape from UCB.
+Unix author Ken Thompson returned to his alma mater, University of California Berkeley (UCB), in 1975 and taught the kernel line-by-line.
+This ultimately resulted in an evolving system known as BSD (Berkeley Standard Distribution).
+UCB converted Unix to 32-bits, added virtual memory, and implemented the version of the TCP/IP stack upon which the Internet was essentially built.
+UCB made BSD available for the cost of media, under what became known as "the BSD license".
+A customer purchased Unix from AT&T and then ordered a BSD tape from UCB.
-In the mid-1980s a government anti-trust case against AT&T ended with the break-up of AT&T. AT&T still owned Unix and was now able to sell it. AT&T embarked on an aggressive licensing effort and most commercial Unixes of the day became AT&T-derived.
+In the mid-1980s a government anti-trust case against AT&T ended with the break-up of AT&T.
+AT&T still owned Unix and was now able to sell it.
+AT&T embarked on an aggressive licensing effort and most commercial Unixes of the day became AT&T-derived.
-In the early 1990's AT&T sued UCB over license violations related to BSD. UCB discovered that AT&T had incorporated, without acknowledgment or payment, many improvements due to BSD into AT&T's products, and a lengthy court case, primarily between AT&T and UCB, ensued. During this period some UCB programmers embarked on a project to rewrite any AT&T code associated with BSD. This project resulted in a system called BSD 4.4-lite (lite because it was not a complete system; it lacked 6 key AT&T files).
+In the early 1990's AT&T sued UCB over license violations related to BSD.
+UCB discovered that AT&T had incorporated, without acknowledgment or payment,
+many improvements due to BSD into AT&T's products, and a lengthy court case, primarily between AT&T and UCB, ensued.
+During this period some UCB programmers embarked on a project to rewrite any AT&T code associated with BSD.
+This project resulted in a system called BSD 4.4-lite (lite because it was not a complete system; it lacked 6 key AT&T files).
-A lengthy series of articles published slightly later in Dr. Dobbs magazine described a BSD-derived 386 PC version of Unix, with BSD-licensed replacement files for the 6 missing 4.4 lite files. This system, named 386BSD, was due to ex-UCB programmer William Jolitz. It became the original basis of all the PC BSDs in use today.
+A lengthy series of articles published slightly later in Dr. Dobbs magazine described a BSD-derived 386 PC version of Unix, with BSD-licensed replacement files for the 6 missing 4.4 lite files.
+This system, named 386BSD, was due to ex-UCB programmer William Jolitz.
+It became the original basis of all the PC BSDs in use today.
-In the mid 1990s, Novell purchased AT&T's Unix rights and a (then secret) agreement was reached to terminate the lawsuit. UCB soon terminated its support for BSD.
+In the mid 1990s, Novell purchased AT&T's Unix rights and a (then secret) agreement was reached to terminate the lawsuit.
+UCB soon terminated its support for BSD.
[[current-bsdl]]
== The Current State of FreeBSD and BSD Licenses
-The so-called http://www.opensource.org/licenses/bsd-license.php[new BSD license] applied to FreeBSD within the last few years is effectively a statement that you can do anything with the program or its source, but you do not have any warranty and none of the authors has any liability (basically, you cannot sue anybody). This new BSD license is intended to encourage product commercialization. Any BSD code can be sold or included in proprietary products without any restrictions on the availability of your code or your future behavior.
+The so-called http://www.opensource.org/licenses/bsd-license.php[new BSD license] applied to FreeBSD within the last few years is effectively a statement that you can do anything with the program or its source,
+but you do not have any warranty and none of the authors has any liability (basically, you cannot sue anybody).
+This new BSD license is intended to encourage product commercialization.
+Any BSD code can be sold or included in proprietary products without any restrictions on the availability of your code or your future behavior.
-Do not confuse the new BSD license with "public domain". While an item in the public domain is also free for all to use, it has no owner.
+Do not confuse the new BSD license with "public domain".
+While an item in the public domain is also free for all to use, it has no owner.
[[origins-gpl]]
== The origins of the GPL
-While the future of Unix had been so muddled in the late 1980s and early 1990s, the GPL, another development with important licensing considerations, reached fruition.
+While the future of Unix had been so muddled in the late 1980s and early 1990s, the GPL,
+another development with important licensing considerations, reached fruition.
-Richard Stallman, the developer of Emacs, was a member of the staff at MIT when his lab switched from home-grown to proprietary systems. Stallman became upset when he found that he could not legally add minor improvements to the system. (Many of Stallman's co-workers had left to form two companies based on software developed at MIT and licensed by MIT; there appears to have been disagreement over access to the source code for this software). Stallman devised an alternative to the commercial software license and called it the GPL, or "GNU Public License". He also started a non-profit foundation, the http://www.fsf.org[Free Software Foundation] (FSF), which intended to develop an entire operating system, including all associated software, that would not be subject to proprietary licensing. This system was called GNU, for "GNU is Not Unix".
+Richard Stallman, the developer of Emacs, was a member of the staff at MIT when his lab switched from home-grown to proprietary systems.
+Stallman became upset when he found that he could not legally add minor improvements to the system.
+(Many of Stallman's co-workers had left to form two companies based on software developed at MIT and licensed by MIT;
+there appears to have been disagreement over access to the source code for this software).
+Stallman devised an alternative to the commercial software license and called it the GPL, or "GNU Public License".
+He also started a non-profit foundation, the http://www.fsf.org[Free Software Foundation] (FSF),
+which intended to develop an entire operating system, including all associated software, that would not be subject to proprietary licensing.
+This system was called GNU, for "GNU is Not Unix".
-The GPL was designed to be the antithesis of the standard proprietary license. To this end, any modifications that were made to a GPL program were required to be given back to the GPL community (by requiring that the source of the program be available to the user) and any program that used or linked to GPL code was required to be under the GPL. The GPL was intended to keep software from becoming proprietary. As the last paragraph of the GPL states:
+The GPL was designed to be the antithesis of the standard proprietary license.
+To this end, any modifications that were made to a GPL program were required to be given back to the GPL community (by requiring that the source of the program be available to the user) and any program that used or linked to GPL code was required to be under the GPL.
+The GPL was intended to keep software from becoming proprietary.
+As the last paragraph of the GPL states:
-"This General Public License does not permit incorporating your program into proprietary programs."[1]
+"This General Public License does not permit incorporating your program into proprietary programs."<<one>>
The http://www.opensource.org/licenses/gpl-license.php[GPL] is a complex license so here are some rules of thumb when using the GPL:
@@ -81,53 +130,90 @@ The http://www.opensource.org/licenses/gpl-license.php[GPL] is a complex license
* output of a program does not count as a derivative work. This enables the gcc compiler to be used in commercial environments without legal problems.
* since the Linux kernel is under the GPL, any code statically linked with the Linux kernel must be GPLed. This requirement can be circumvented by dynamically linking loadable kernel modules. This permits companies to distribute binary drivers, but often has the disadvantage that they will only work for particular versions of the Linux kernel.
-Due in part to its complexity, in many parts of the world today the legalities of the GPL are being ignored in regard to Linux and related software. The long-term ramifications of this are unclear.
+Due in part to its complexity, in many parts of the world today the legalities of the GPL are being ignored in regard to Linux and related software.
+The long-term ramifications of this are unclear.
[[origins-lgpl]]
== The origins of Linux and the LGPL
-While the commercial Unix wars raged, the Linux kernel was developed as a PC Unix clone. Linus Torvalds credits the existence of the GNU C compiler and the associated GNU tools for the existence of Linux. He put the Linux kernel under the GPL.
+While the commercial Unix wars raged, the Linux kernel was developed as a PC Unix clone.
+Linus Torvalds credits the existence of the GNU C compiler and the associated GNU tools for the existence of Linux.
+He put the Linux kernel under the GPL.
-Remember that the GPL requires anything that statically links to any code under the GPL also be placed under the GPL. The source for this code must thus be made available to the user of the program. Dynamic linking, however, is not considered a violation of the GPL. Pressure to put proprietary applications on Linux became overwhelming. Such applications often must link with system libraries. This resulted in a modified version of the GPL called the http://www.opensource.org/licenses/lgpl-license.php[LGPL] ("Library", since renamed to "Lesser", GPL). The LGPL allows proprietary code to be linked to the GNU C library, glibc. You do not have to release the source code which has been dynamically linked to an LGPLed library.
+Remember that the GPL requires anything that statically links to any code under the GPL also be placed under the GPL.
+The source for this code must thus be made available to the user of the program.
+Dynamic linking, however, is not considered a violation of the GPL.
+Pressure to put proprietary applications on Linux became overwhelming.
+Such applications often must link with system libraries.
+This resulted in a modified version of the GPL called the http://www.opensource.org/licenses/lgpl-license.php[LGPL] ("Library", since renamed to "Lesser", GPL).
+The LGPL allows proprietary code to be linked to the GNU C library, glibc.
+You do not have to release the source code which has been dynamically linked to an LGPLed library.
-If you statically link an application with glibc, such as is often required in embedded systems, you cannot keep your application proprietary, that is, the source must be released. Both the GPL and LGPL require any modifications to the code directly under the license to be released.
+If you statically link an application with glibc, such as is often required in embedded systems,
+you cannot keep your application proprietary, that is, the source must be released.
+Both the GPL and LGPL require any modifications to the code directly under the license to be released.
[[orphaning]]
== Open Source licenses and the Orphaning Problem
-One of the serious problems associated with proprietary software is known as "orphaning". This occurs when a single business failure or change in a product strategy causes a huge pyramid of dependent systems and companies to fail for reasons beyond their control. Decades of experience have shown that the momentary size or success of a software supplier is no guarantee that their software will remain available, as current market conditions and strategies can change rapidly.
+One of the serious problems associated with proprietary software is known as "orphaning".
+This occurs when a single business failure or change in a product strategy causes a huge pyramid of dependent systems and companies to fail for reasons beyond their control.
+Decades of experience have shown that the momentary size or success of a software supplier is no guarantee that their software will remain available, as current market conditions and strategies can change rapidly.
The GPL attempts to prevent orphaning by severing the link to proprietary intellectual property.
-A BSD license gives a small company the equivalent of software-in-escrow without any legal complications or costs. If a BSD-licensed program becomes orphaned, a company can simply take over, in a proprietary manner, the program on which they are dependent. An even better situation occurs when a BSD code-base is maintained by a small informal consortium, since the development process is not dependent on the survival of a single company or product line. The survivability of the development team when they are mentally in the zone is much more important than simple physical availability of the source code.
+A BSD license gives a small company the equivalent of software-in-escrow without any legal complications or costs.
+If a BSD-licensed program becomes orphaned, a company can simply take over, in a proprietary manner, the program on which they are dependent.
+An even better situation occurs when a BSD code-base is maintained by a small informal consortium, since the development process is not dependent on the survival of a single company or product line.
+The survivability of the development team when they are mentally in the zone is much more important than simple physical availability of the source code.
[[license-cannot]]
== What a license cannot do
-No license can guarantee future software availability. Although a copyright holder can traditionally change the terms of a copyright at anytime, the presumption in the BSD community is that such an attempt simply causes the source to fork.
+No license can guarantee future software availability.
+Although a copyright holder can traditionally change the terms of a copyright at anytime, the presumption in the BSD community is that such an attempt simply causes the source to fork.
-The GPL explicitly disallows revoking the license. It has occurred, however, that a company (Mattel) purchased a GPL copyright (cphack), revoked the entire copyright, went to court, and prevailed [2]. That is, they legally revoked the entire distribution and all derivative works based on the copyright. Whether this could happen with a larger and more dispersed distribution is an open question; there is also some confusion regarding whether the software was really under the GPL.
+The GPL explicitly disallows revoking the license.
+It has occurred, however, that a company (Mattel) purchased a GPL copyright (cphack), revoked the entire copyright, went to court, and prevailed <<two>>.
+That is, they legally revoked the entire distribution and all derivative works based on the copyright.
+Whether this could happen with a larger and more dispersed distribution is an open question;
+there is also some confusion regarding whether the software was really under the GPL.
-In another example, Red Hat purchased Cygnus, an engineering company that had taken over development of the FSF compiler tools. Cygnus was able to do so because they had developed a business model in which they sold support for GNU software. This enabled them to employ some 50 engineers and drive the direction of the programs by contributing the preponderance of modifications. As Donald Rosenberg states "projects using licenses like the GPL...live under constant threat of having someone take over the project by producing a better version of the code and doing it faster than the original owners." [3]
+In another example, Red Hat purchased Cygnus, an engineering company that had taken over development of the FSF compiler tools.
+Cygnus was able to do so because they had developed a business model in which they sold support for GNU software.
+This enabled them to employ some 50 engineers and drive the direction of the programs by contributing the preponderance of modifications.
+As Donald Rosenberg states "projects using licenses like the GPL...live under constant threat of having someone take over the project by producing a better version of the code and doing it faster than the original owners." <<three>>
[[gpl-advantages]]
== GPL Advantages and Disadvantages
-A common reason to use the GPL is when modifying or extending the gcc compiler. This is particularly apt when working with one-off specialty CPUs in environments where all software costs are likely to be considered overhead, with minimal expectations that others will use the resulting compiler.
+A common reason to use the GPL is when modifying or extending the gcc compiler.
+This is particularly apt when working with one-off specialty CPUs in environments where all software costs are likely to be considered overhead, with minimal expectations that others will use the resulting compiler.
-The GPL is also attractive to small companies selling CDs in an environment where "buy-low, sell-high" may still give the end-user a very inexpensive product. It is also attractive to companies that expect to survive by providing various forms of technical support, including documentation, for the GPLed intellectual property world.
+The GPL is also attractive to small companies selling CDs in an environment where "buy-low, sell-high" may still give the end-user a very inexpensive product.
+It is also attractive to companies that expect to survive by providing various forms of technical support, including documentation, for the GPLed intellectual property world.
-A less publicized and unintended use of the GPL is that it is very favorable to large companies that want to undercut software companies. In other words, the GPL is well suited for use as a marketing weapon, potentially reducing overall economic benefit and contributing to monopolistic behavior.
+A less publicized and unintended use of the GPL is that it is very favorable to large companies that want to undercut software companies.
+In other words, the GPL is well suited for use as a marketing weapon, potentially reducing overall economic benefit and contributing to monopolistic behavior.
-The GPL can present a real problem for those wishing to commercialize and profit from software. For example, the GPL adds to the difficulty a graduate student will have in directly forming a company to commercialize his research results, or the difficulty a student will have in joining a company on the assumption that a promising research project will be commercialized.
+The GPL can present a real problem for those wishing to commercialize and profit from software.
+For example, the GPL adds to the difficulty a graduate student will have in directly forming a company to commercialize his research results, or the difficulty a student will have in joining a company on the assumption that a promising research project will be commercialized.
-For those who must work with statically-linked implementations of multiple software standards, the GPL is often a poor license, because it precludes using proprietary implementations of the standards. The GPL thus minimizes the number of programs that can be built using a GPLed standard. The GPL was intended to not provide a mechanism to develop a standard on which one engineers proprietary products. (This does not apply to Linux applications because they do not statically link, rather they use a trap-based API.)
+For those who must work with statically-linked implementations of multiple software standards, the GPL is often a poor license, because it precludes using proprietary implementations of the standards.
+The GPL thus minimizes the number of programs that can be built using a GPLed standard.
+The GPL was intended to not provide a mechanism to develop a standard on which one engineers proprietary products.
+(This does not apply to Linux applications because they do not statically link, rather they use a trap-based API.)
-The GPL attempts to make programmers contribute to an evolving suite of programs, then to compete in the distribution and support of this suite. This situation is unrealistic for many required core system standards, which may be applied in widely varying environments which require commercial customization or integration with legacy standards under existing (non-GPL) licenses. Real-time systems are often statically linked, so the GPL and LGPL are definitely considered potential problems by many embedded systems companies.
+The GPL attempts to make programmers contribute to an evolving suite of programs, then to compete in the distribution and support of this suite.
+This situation is unrealistic for many required core system standards, which may be applied in widely varying environments which require commercial customization or integration with legacy standards under existing (non-GPL) licenses.
+Real-time systems are often statically linked, so the GPL and LGPL are definitely considered potential problems by many embedded systems companies.
-The GPL is an attempt to keep efforts, regardless of demand, at the research and development stages. This maximizes the benefits to researchers and developers, at an unknown cost to those who would benefit from wider distribution.
+The GPL is an attempt to keep efforts, regardless of demand, at the research and development stages.
+This maximizes the benefits to researchers and developers, at an unknown cost to those who would benefit from wider distribution.
-The GPL was designed to keep research results from transitioning to proprietary products. This step is often assumed to be the last step in the traditional technology transfer pipeline and it is usually difficult enough under the best of circumstances; the GPL was intended to make it impossible.
+The GPL was designed to keep research results from transitioning to proprietary products.
+This step is often assumed to be the last step in the traditional technology transfer pipeline and it is usually difficult enough under the best of circumstances;
+the GPL was intended to make it impossible.
[[bsd-advantages]]
== BSD Advantages
@@ -140,19 +226,32 @@ A BSD style license is a good choice for long duration research or other project
This final consideration may often be the dominant one, as it was when the Apache project decided upon its license:
-"This type of license is ideal for promoting the use of a reference body of code that implements a protocol for common service. This is another reason why we choose it for the Apache group - many of us wanted to see HTTP survive and become a true multiparty standard, and would not have minded in the slightest if Microsoft or Netscape choose to incorporate our HTTP engine or any other component of our code into their products, if it helped further the goal of keeping HTTP common... All this means that, strategically speaking, the project needs to maintain sufficient momentum, and that participants realize greater value by contributing their code to the project, even code that would have had value if kept proprietary."
+"This type of license is ideal for promoting the use of a reference body of code that implements a protocol for common service.
+This is another reason why we choose it for the Apache group - many of us wanted to see HTTP survive and become a true multiparty standard,
+and would not have minded in the slightest if Microsoft or Netscape choose to incorporate our HTTP engine or any other component of our code into their products, if it helped further the goal of keeping HTTP common... All this means that, strategically speaking, the project needs to maintain sufficient momentum, and that participants realize greater value by contributing their code to the project, even code that would have had value if kept proprietary."
-Developers tend to find the BSD license attractive as it keeps legal issues out of the way and lets them do whatever they want with the code. In contrast, those who expect primarily to use a system rather than program it, or expect others to evolve the code, or who do not expect to make a living from their work associated with the system (such as government employees), find the GPL attractive, because it forces code developed by others to be given to them and keeps their employer from retaining copyright and thus potentially "burying" or orphaning the software. If you want to force your competitors to help you, the GPL is attractive.
+Developers tend to find the BSD license attractive as it keeps legal issues out of the way and lets them do whatever they want with the code.
+In contrast, those who expect primarily to use a system rather than program it, or expect others to evolve the code, or who do not expect to make a living from their work associated with the system (such as government employees), find the GPL attractive, because it forces code developed by others to be given to them and keeps their employer from retaining copyright and thus potentially "burying" or orphaning the software.
+If you want to force your competitors to help you, the GPL is attractive.
-A BSD license is not simply a gift. The question "why should we help our competitors or let them steal our work?" comes up often in relation to a BSD license. Under a BSD license, if one company came to dominate a product niche that others considered strategic, the other companies can, with minimal effort, form a mini-consortium aimed at reestablishing parity by contributing to a competitive BSD variant that increases market competition and fairness. This permits each company to believe that it will be able to profit from some advantage it can provide, while also contributing to economic flexibility and efficiency. The more rapidly and easily the cooperating members can do this, the more successful they will be. A BSD license is essentially a minimally complicated license that enables such behavior.
+A BSD license is not simply a gift.
+The question "why should we help our competitors or let them steal our work?" comes up often in relation to a BSD license.
+Under a BSD license, if one company came to dominate a product niche that others considered strategic, the other companies can, with minimal effort, form a mini-consortium aimed at reestablishing parity by contributing to a competitive BSD variant that increases market competition and fairness.
+This permits each company to believe that it will be able to profit from some advantage it can provide, while also contributing to economic flexibility and efficiency.
+The more rapidly and easily the cooperating members can do this, the more successful they will be.
+A BSD license is essentially a minimally complicated license that enables such behavior.
-A key effect of the GPL, making a complete and competitive Open Source system widely available at cost of media, is a reasonable goal. A BSD style license, in conjunction with ad-hoc-consortiums of individuals, can achieve this goal without destroying the economic assumptions built around the deployment-end of the technology transfer pipeline.
+A key effect of the GPL, making a complete and competitive Open Source system widely available at cost of media, is a reasonable goal.
+A BSD style license, in conjunction with ad-hoc-consortiums of individuals, can achieve this goal without destroying the economic assumptions built around the deployment-end of the technology transfer pipeline.
[[recommendations]]
== Specific Recommendations for using a BSD license
-* The BSD license is preferable for transferring research results in a way that will widely be deployed and most benefit an economy. As such, research funding agencies, such as the NSF, ONR and DARPA, should encourage in the earliest phases of funded research projects, the adoption of BSD style licenses for software, data, results, and open hardware. They should also encourage formation of standards based around implemented Open Source systems and ongoing Open Source projects.
-* Government policy should minimize the costs and difficulties in moving from research to deployment. When possible, grants should require results to be available under a commercialization friendly BSD style license.
+* The BSD license is preferable for transferring research results in a way that will widely be deployed and most benefit an economy.
+As such, research funding agencies, such as the NSF, ONR and DARPA, should encourage in the earliest phases of funded research projects, the adoption of BSD style licenses for software, data, results, and open hardware.
+They should also encourage formation of standards based around implemented Open Source systems and ongoing Open Source projects.
+* Government policy should minimize the costs and difficulties in moving from research to deployment.
+When possible, grants should require results to be available under a commercialization friendly BSD style license.
* In many cases, the long-term results of a BSD style license more accurately reflect the goals proclaimed in the research charter of universities than what occurs when results are copyrighted or patented and subject to proprietary university licensing. Anecdotal evidence exists that universities are financially better rewarded in the long run by releasing research results and then appealing to donations from commercially successful alumni.
* Companies have long recognized that the creation of de facto standards is a key marketing technique. The BSD license serves this role well, if a company really has a unique advantage in evolving the system. The license is legally attractive to the widest audience while the company's expertise ensures their control. There are times when the GPL may be the appropriate vehicle for an attempt to create such a standard, especially when attempting to undermine or co-opt others. The GPL, however, penalizes the evolution of that standard, because it promotes a suite rather than a commercially applicable standard. Use of such a suite constantly raises commercialization and legal issues. It may not be possible to mix standards when some are under the GPL and others are not. A true technical standard should not mandate exclusion of other standards for non-technical reasons.
* Companies interested in promoting an evolving standard, which can become the core of other companies' commercial products, should be wary of the GPL. Regardless of the license used, the resulting software will usually devolve to whoever actually makes the majority of the engineering changes and most understands the state of the system. The GPL simply adds more legal friction to the result.
@@ -163,25 +262,22 @@ A key effect of the GPL, making a complete and competitive Open Source system wi
[[conclusion]]
== Conclusion
-In contrast to the GPL, which is designed to prevent the proprietary commercialization of Open Source code, the BSD license places minimal restrictions on future behavior. This allows BSD code to remain Open Source or become integrated into commercial solutions, as a project's or company's needs change. In other words, the BSD license does not become a legal time-bomb at any point in the development process.
+In contrast to the GPL, which is designed to prevent the proprietary commercialization of Open Source code, the BSD license places minimal restrictions on future behavior.
+This allows BSD code to remain Open Source or become integrated into commercial solutions, as a project's or company's needs change.
+In other words, the BSD license does not become a legal time-bomb at any point in the development process.
In addition, since the BSD license does not come with the legal complexity of the GPL or LGPL licenses, it allows developers and companies to spend their time creating and promoting good code rather than worrying if that code violates licensing.
[[addenda]]
+[bibliography]
== Bibliographical References
-[.programlisting]
-....
-[1] http://www.gnu.org/licenses/gpl.html
+* [[[one,1]]] http://www.gnu.org/licenses/gpl.html
-[2] http://archives.cnn.com/2000/TECH/computing/03/28/cyberpatrol.mirrors/
+* [[[two,2]]] http://archives.cnn.com/2000/TECH/computing/03/28/cyberpatrol.mirrors/
-[3] Open Source: the Unauthorized White Papers, Donald K. Rosenberg, IDG Books,
- 2000. Quotes are from page 114, ``Effects of the GNU GPL''.
+* [[[three,3]]] Open Source: the Unauthorized White Papers, Donald K. Rosenberg, IDG Books, 2000. Quotes are from page 114, "Effects of the GNU GPL".
-[4] In the "What License to Use?" section of
- http://www.oreilly.com/catalog/opensources/book/brian.html
+* [[[four,4]]] In the "What License to Use?" section of http://www.oreilly.com/catalog/opensources/book/brian.html
-This whitepaper is a condensation of an original work available at
-http://alumni.cse.ucsc.edu/~brucem/open_source_license.htm
-....
+This whitepaper is a condensation of an original work available at http://alumni.cse.ucsc.edu/~brucem/open_source_license.htm
diff --git a/documentation/content/en/articles/building-products/_index.adoc b/documentation/content/en/articles/building-products/_index.adoc
index ce85ee3757..8538aea5e8 100644
--- a/documentation/content/en/articles/building-products/_index.adoc
+++ b/documentation/content/en/articles/building-products/_index.adoc
@@ -24,7 +24,7 @@ include::shared/en/mailing-lists.adoc[]
include::shared/en/urls.adoc[]
ifeval::["{backend}" == "html5"]
-:imagesdir: ../../images/articles/building-products/
+:imagesdir: ../../../images/articles/building-products/
endif::[]
ifeval::["{backend}" == "pdf"]
@@ -38,9 +38,13 @@ endif::[]
[.abstract-title]
Abstract
-The FreeBSD project is a worldwide, volunteer based, and collaborative project, which develops a portable and high-quality operating system. The FreeBSD project distributes the source code for its product under a liberal license, with the intention of encouraging the use of its code. Collaborating with the FreeBSD project can help organizations reduce their time to market, reduce engineering costs and improve their product quality.
+The FreeBSD project is a worldwide, volunteer based, and collaborative project, which develops a portable and high-quality operating system.
+The FreeBSD project distributes the source code for its product under a liberal license, with the intention of encouraging the use of its code.
+Collaborating with the FreeBSD project can help organizations reduce their time to market, reduce engineering costs and improve their product quality.
-This article examines the issues in using FreeBSD code in appliances and software products. It highlights the characteristics of FreeBSD that make it an excellent substrate for product development. The article concludes by suggesting a few "best practices" for organizations collaborating with the FreeBSD project.
+This article examines the issues in using FreeBSD code in appliances and software products.
+It highlights the characteristics of FreeBSD that make it an excellent substrate for product development.
+The article concludes by suggesting a few "best practices" for organizations collaborating with the FreeBSD project.
'''
@@ -49,13 +53,18 @@ toc::[]
[[introduction]]
== Introduction
-FreeBSD today is well-known as a high-performance server operating system. It is deployed on millions of web servers and internet-facing hosts worldwide. FreeBSD code also forms an integral part of many products, ranging from appliances such as network routers, firewalls, and storage devices, to personal computers. Portions of FreeBSD have also been used in commercial shrink-wrapped software (see <<freebsd-intro>>).
+FreeBSD today is well-known as a high-performance server operating system.
+It is deployed on millions of web servers and internet-facing hosts worldwide.
+FreeBSD code also forms an integral part of many products, ranging from appliances such as network routers, firewalls, and storage devices, to personal computers.
+Portions of FreeBSD have also been used in commercial shrink-wrapped software (see <<freebsd-intro>>).
In this article we look at the link:https://www.FreeBSD.org/[FreeBSD project] as a software engineering resource-as a collection of building blocks and processes which you can use to build products.
-While FreeBSD's source is distributed freely to the public, to fully enjoy the benefits of the project's work, organizations need to _collaborate_ with the project. In subsequent sections of this article we discuss effective means of collaboration with the project and the pitfalls that need to be avoided while doing so.
+While FreeBSD's source is distributed freely to the public, to fully enjoy the benefits of the project's work, organizations need to _collaborate_ with the project.
+In subsequent sections of this article we discuss effective means of collaboration with the project and the pitfalls that need to be avoided while doing so.
-*Caveat Reader.* The author believes that the characteristics of the FreeBSD Project listed in this article were substantially true at the time the article was conceived and written (2005). However, the reader should keep in mind that the practices and processes used by open-source communities can change over time, and that the information in this article should therefore be taken as indicative rather than normative.
+*Caveat Reader.* The author believes that the characteristics of the FreeBSD Project listed in this article were substantially true at the time the article was conceived and written (2005).
+However, the reader should keep in mind that the practices and processes used by open-source communities can change over time, and that the information in this article should therefore be taken as indicative rather than normative.
=== Target Audience
@@ -94,7 +103,8 @@ FreeBSD makes an excellent foundation on which to build products:
* The project offers exceptional transparency into its workings, allowing organizations using its code to plan effectively for the future.
* The culture of the FreeBSD project, carried over from the Computer Science Research Group at The University of California, Berkeley <<McKu1999-1>>, fosters high-quality work. Some features in FreeBSD define the state of the art.
-<<GoldGab2005>> examines the business reasons for using open-source in greater detail. For organizations, the benefits of using FreeBSD components in their products include a shorter time to market, lower development costs and lower development risks.
+<<GoldGab2005>> examines the business reasons for using open-source in greater detail.
+For organizations, the benefits of using FreeBSD components in their products include a shorter time to market, lower development costs and lower development risks.
=== Building with FreeBSD
@@ -108,21 +118,28 @@ By being "downstream" of the project, organizations leverage the new features, b
FreeBSD ships with a self-hosting development environment that allows easy creation of such configurations.
* As a Unix compatible environment for the management functions of high-end storage and networking devices, running on a separate processor "blade".
+
-FreeBSD provides the tools for creating dedicated OS and application program images. Its implementation of a BSD unix API is mature and tested. FreeBSD can also provide a stable cross-development environment for the other components of the high-end device.
+FreeBSD provides the tools for creating dedicated OS and application program images.
+Its implementation of a BSD unix API is mature and tested.
+FreeBSD can also provide a stable cross-development environment for the other components of the high-end device.
* As a vehicle to get widespread testing and support from a worldwide team of developers for non-critical "intellectual property".
+
-In this model, organizations contribute useful infrastructural frameworks to the FreeBSD project (for example, see man:netgraph[3]). The widespread exposure that the code gets helps to quickly identify performance issues and bugs. The involvement of top-notch developers also leads to useful extensions to the infrastructure that the contributing organization also benefits from.
+In this model, organizations contribute useful infrastructural frameworks to the FreeBSD project (for example, see man:netgraph[3]).
+The widespread exposure that the code gets helps to quickly identify performance issues and bugs.
+The involvement of top-notch developers also leads to useful extensions to the infrastructure that the contributing organization also benefits from.
* As a development environment supporting cross-development for embedded OSes like http://www.rtems.com/[RTEMS] and http://ecos.sourceware.org/[eCOS].
+
There are many full-fledged development environments in the {numports}-strong collection of applications ported and packaged with FreeBSD.
* As a way to support a Unix-like API in an otherwise proprietary OS, increasing its palatability for application developers.
+
-Here parts of FreeBSD's kernel and application programs are "ported" to run alongside other tasks in the proprietary OS. The availability of a stable and well tested Unix(TM) API implementation can reduce the effort needed to port popular applications to the proprietary OS. As FreeBSD ships with high-quality documentation for its internals and has effective vulnerability management and release engineering processes, the costs of keeping up-to-date are kept low.
+Here parts of FreeBSD's kernel and application programs are "ported" to run alongside other tasks in the proprietary OS.
+The availability of a stable and well tested Unix(TM) API implementation can reduce the effort needed to port popular applications to the proprietary OS.
+As FreeBSD ships with high-quality documentation for its internals and has effective vulnerability management and release engineering processes, the costs of keeping up-to-date are kept low.
[[freebsd-technologies]]
=== Technologies
-There are a large number of technologies supported by the FreeBSD project. A selection of these are listed below:
+There are a large number of technologies supported by the FreeBSD project.
+A selection of these are listed below:
* A complete system that can cross-host itself for link:https://www.FreeBSD.org/platforms/[many architectures:]
* A modular symmetric multiprocessing capable kernel, with loadable kernel modules and a flexible and easy to use configuration system.
@@ -145,20 +162,25 @@ FreeBSD's organizational structure is non-hierarchical.
There are essentially two kinds of contributors to FreeBSD, general users of FreeBSD, and developers with write access (known as _committers_ in the jargon) to the source base.
-There are many thousands of contributors in the first group; the vast majority of contributions to FreeBSD come from individuals in this group. Commit rights (write access) to the repository are granted to individuals who contribute consistently to the project. Commit rights come with additional responsibilities, and new committers are assigned mentors to help them learn the ropes.
+There are many thousands of contributors in the first group; the vast majority of contributions to FreeBSD come from individuals in this group.
+Commit rights (write access) to the repository are granted to individuals who contribute consistently to the project.
+Commit rights come with additional responsibilities, and new committers are assigned mentors to help them learn the ropes.
.FreeBSD Organization
image::freebsd-organization.png[]
Conflict resolution is performed by a nine member "Core Team" that is elected from the group of committers.
-FreeBSD does not have "corporate" committers. Individual committers are required to take responsibility for the changes they introduce to the code. The link:{committers-guide}[FreeBSD Committer's guide] <<ComGuide>> documents the rules and responsibilities for committers.
+FreeBSD does not have "corporate" committers.
+Individual committers are required to take responsibility for the changes they introduce to the code.
+The link:{committers-guide}[FreeBSD Committer's guide] <<ComGuide>> documents the rules and responsibilities for committers.
FreeBSD's project model is examined in detail in <<Nik2005>>.
=== FreeBSD Release Engineering Processes
-FreeBSD's release engineering processes play a major role in ensuring that its released versions are of a high quality. At any point of time, FreeBSD's volunteers support multiple code lines (<<fig-freebsd-branches, FreeBSD Release Branches>>):
+FreeBSD's release engineering processes play a major role in ensuring that its released versions are of a high quality.
+At any point of time, FreeBSD's volunteers support multiple code lines (<<fig-freebsd-branches, FreeBSD Release Branches>>):
* New features and disruptive code enters on the development branch, also known as the _-CURRENT_ branch.
* _-STABLE_ branches are code lines that are branched from HEAD at regular intervals. Only tested code is allowed onto a -STABLE branch. New features are allowed once they have been tested and stabilized in the -CURRENT branch.
@@ -170,9 +192,11 @@ image::freebsd-branches.png[]
Code lines are kept alive for as long as there is user and developer interest in them.
-Machine architectures are grouped into "tiers"; _Tier 1_ architectures are fully supported by the project's release engineering and security teams, _Tier 2_ architectures are supported on a best effort basis, and experimental architectures comprise _Tier 3_. The list of link:{committers-guide}#archs[supported architectures] is part of the FreeBSD documentation collection.
+Machine architectures are grouped into "tiers"; _Tier 1_ architectures are fully supported by the project's release engineering and security teams, _Tier 2_ architectures are supported on a best effort basis, and experimental architectures comprise _Tier 3_.
+The list of link:{committers-guide}#archs[supported architectures] is part of the FreeBSD documentation collection.
-The release engineering team publishes a link:https://www.FreeBSD.org/releng/[road map] for future releases of FreeBSD on the project's web site. The dates laid down in the road map are not deadlines; FreeBSD is released when its code and documentation are ready.
+The release engineering team publishes a link:https://www.FreeBSD.org/releng/[road map] for future releases of FreeBSD on the project's web site.
+The dates laid down in the road map are not deadlines; FreeBSD is released when its code and documentation are ready.
FreeBSD's release engineering processes are described in <<RelEngDoc>>.
@@ -181,7 +205,10 @@ FreeBSD's release engineering processes are described in <<RelEngDoc>>.
Open-source projects like FreeBSD offer finished code of a very high quality.
-While access to quality source code can reduce the cost of initial development, in the long-term the costs of managing change begin to dominate. As computing environments change over the years and new security vulnerabilities are discovered, your product too needs to change and adapt. Using open-source code is best viewed not as a one-off activity, but as an __ongoing process__. The best projects to collaborate with are the ones that are __live__; i.e., with an active community, clear goals and a transparent working style.
+While access to quality source code can reduce the cost of initial development, in the long-term the costs of managing change begin to dominate.
+As computing environments change over the years and new security vulnerabilities are discovered, your product too needs to change and adapt.
+Using open-source code is best viewed not as a one-off activity, but as an __ongoing process__.
+The best projects to collaborate with are the ones that are __live__; i.e., with an active community, clear goals and a transparent working style.
* FreeBSD has an active developer community around it. At the time of writing there are many thousands of contributors from every populated continent in the world and over 300 individuals with write access to the project's source repositories.
* The goals of the FreeBSD project are <<Hub1994>>:
@@ -196,7 +223,8 @@ While access to quality source code can reduce the cost of initial development,
To be able to work effectively with the FreeBSD project, you need to understand the project's culture.
-Volunteer driven projects operate under different rules than for-profit corporates. A common mistake that companies make when venturing into the open-source world is that of underplaying these differences.
+Volunteer driven projects operate under different rules than for-profit corporates.
+A common mistake that companies make when venturing into the open-source world is that of underplaying these differences.
*Motivation.* Most contributions to FreeBSD are done voluntarily without monetary rewards entering the picture. The factors that motivate individuals are complex, ranging from altruism, to an interest in solving the kinds of problems that FreeBSD attempts to solve. In this environment, "elegance is never optional"<<Nor1993>>.
@@ -204,13 +232,15 @@ Volunteer driven projects operate under different rules than for-profit corporat
The project values long-term perspectives <<Nor2001>>. A frequent acronym encountered in the project is DTRT, which stands for "Do The Right Thing".
-*Development Processes.* Computer programs are tools for communication: at one level programmers communicate their intentions using a precise notation to a tool (a compiler) that translates their instructions to executable code. At another level, the same notation is used for communication of intent between two programmers.
+*Development Processes.* Computer programs are tools for communication: at one level programmers communicate their intentions using a precise notation to a tool (a compiler) that translates their instructions to executable code.
+At another level, the same notation is used for communication of intent between two programmers.
-Formal specifications and design documents are seldom used in the project. Clear and well-written code and well-written change logs (<<fig-change-log, A sample change log entry>>) are used in their place. FreeBSD development happens by "rough consensus and running code"<<Carp1996>>.
+Formal specifications and design documents are seldom used in the project.
+Clear and well-written code and well-written change logs (<<fig-change-log, A sample change log entry>>) are used in their place.
+FreeBSD development happens by "rough consensus and running code"<<Carp1996>>.
[.programlisting]
....
-
r151864 | bde | 2005-10-29 09:34:50 -0700 (Sat, 29 Oct 2005) | 13 lines
Changed paths:
M /head/lib/msun/src/e_rem_pio2f.c
@@ -232,22 +262,25 @@ This speeds up arg reduction by a factor of 2 for |x| between 3*pi/4 and
Communication between programmers is enhanced by the use of a common coding standard man:style[9].
-*Communication Channels.* FreeBSD's contributors are spread across the world. Email (and to a lesser extent, IRC) is the preferred means of communication in the project.
+*Communication Channels.* FreeBSD's contributors are spread across the world.
+Email (and to a lesser extent, IRC) is the preferred means of communication in the project.
=== Best Practices for collaborating with the FreeBSD project
We now look at a few best practices for making the best use of FreeBSD in product development.
Plan for the long term::
-Setup processes that help in tracking the development of FreeBSD. For example:
+Setup processes that help in tracking the development of FreeBSD.
+For example:
+
*Track FreeBSD source code.* The project makes it easy to mirror its SVN repository using link:{committers-guide}#svn-advanced-use-setting-up-svnsync[svnsync]. Having the complete history of the source is useful when debugging complex problems and offers valuable insight into the intentions of the original developers. Use a capable source control system that allows you to easily merge changes between the upstream FreeBSD code base and your own in-house code.
+
-<<fig-svn-blame, An annotated source listing generated using `svn blame`>> shows a portion of an annotated listing of the file referenced by the change log in <<fig-change-log, A sample change log entry>>. The ancestry of each line of the source is clearly visible. Annotated listings showing the history of every file that is part of FreeBSD are https://svnweb.freebsd.org/[available on the web].
+<<fig-svn-blame, An annotated source listing generated using `svn blame`>> shows a portion of an annotated listing of the file referenced by the change log in <<fig-change-log, A sample change log entry>>.
+The ancestry of each line of the source is clearly visible.
+Annotated listings showing the history of every file that is part of FreeBSD are https://svnweb.freebsd.org/[available on the web].
+
[.programlisting]
....
-
#REV #WHO #DATE #TEXT
176410 bde 2008-02-19 07:42:46 -0800 (Tue, 19 Feb 2008) #include <sys/cdefs.h>
@@ -268,31 +301,48 @@ Setup processes that help in tracking the development of FreeBSD. For example:
+
*Use a gatekeeper.* Appoint a _gatekeeper_ to monitor FreeBSD development, to keep an eye out for changes that could potentially impact your products.
+
-*Report bugs upstream.* If you notice bug in the FreeBSD code that you are using, file a https://www.FreeBSD.org/support/bugreports/[bug report]. This step helps ensure that you do not have to fix the bug the next time you take a code drop from upstream.
+*Report bugs upstream.* If you notice bug in the FreeBSD code that you are using, file a https://www.FreeBSD.org/support/bugreports/[bug report].
+This step helps ensure that you do not have to fix the bug the next time you take a code drop from upstream.
Leverage FreeBSD's release engineering efforts::
-Use code from a -STABLE development branch of FreeBSD. These development branches are formally supported by FreeBSD's release engineering and security teams and comprise of tested code.
+Use code from a -STABLE development branch of FreeBSD.
+These development branches are formally supported by FreeBSD's release engineering and security teams and comprise of tested code.
Donate code to reduce costs::
-A major proportion of the costs associated with developing products is that of doing maintenance. By donating non-critical code to the project, you benefit by having your code see much wider exposure than it would otherwise get. This in turn leads to more bugs and security vulnerabilities being flushed out and performance anomalies being identified and fixed.
+A major proportion of the costs associated with developing products is that of doing maintenance.
+By donating non-critical code to the project, you benefit by having your code see much wider exposure than it would otherwise get.
+This in turn leads to more bugs and security vulnerabilities being flushed out and performance anomalies being identified and fixed.
Get support effectively::
-For products with tight deadlines, it is recommended that you hire or enter into a consulting agreement with a developer or firm with FreeBSD experience. The {freebsd-jobs} is a useful communication channel to find talent. The FreeBSD project maintains a link:https://www.FreeBSD.org/commercial/consult_bycat/[gallery of consultants and consulting firms] undertaking FreeBSD work. The http://www.bsdcertification.org/[BSD Certification Group] offers certification for all the major BSD derived OSes.
+For products with tight deadlines, it is recommended that you hire or enter into a consulting agreement with a developer or firm with FreeBSD experience.
+The {freebsd-jobs} is a useful communication channel to find talent.
+The FreeBSD project maintains a link:https://www.FreeBSD.org/commercial/consult_bycat/[gallery of consultants and consulting firms] undertaking FreeBSD work.
+The http://www.bsdcertification.org/[BSD Certification Group] offers certification for all the major BSD derived OSes.
+
-For less critical needs, you can ask for help on the http://lists.FreeBSD.org/mailman/listinfo[project mailing lists]. A useful guide to follow when asking for help is given in <<Ray2004>>.
+For less critical needs, you can ask for help on the http://lists.FreeBSD.org/mailman/listinfo[project mailing lists].
+A useful guide to follow when asking for help is given in <<Ray2004>>.
Publicize your involvement::
You are not required to publicize your use of FreeBSD, but doing so helps both your effort as well as that of the project.
+
-Letting the FreeBSD community know that your company uses FreeBSD helps improve your chances of attracting high quality talent. A large roster of support for FreeBSD also means more mind share for it among developers. This in turn yields a healthier foundation for your future.
+Letting the FreeBSD community know that your company uses FreeBSD helps improve your chances of attracting high quality talent.
+A large roster of support for FreeBSD also means more mind share for it among developers.
+This in turn yields a healthier foundation for your future.
Support FreeBSD developers::
-Sometimes the most direct way to get a desired feature into FreeBSD is to support a developer who is already looking at a related problem. Help can range from hardware donations to direct financial assistance. In some countries, donations to the FreeBSD project enjoy tax benefits. The project has a dedicated link:https://www.FreeBSD.org/donations/[donations liaison] to assist donors. The project also maintains a web page where developers link:https://www.FreeBSD.org/donations/wantlist/[list their needs].
+Sometimes the most direct way to get a desired feature into FreeBSD is to support a developer who is already looking at a related problem.
+Help can range from hardware donations to direct financial assistance.
+In some countries, donations to the FreeBSD project enjoy tax benefits.
+The project has a dedicated link:https://www.FreeBSD.org/donations/[donations liaison] to assist donors.
+The project also maintains a web page where developers link:https://www.FreeBSD.org/donations/wantlist/[list their needs].
+
As a policy the FreeBSD project link:{contributors}[acknowledges] all contributions received on its web site.
[[conclusion]]
== Conclusion
-The FreeBSD project's goals are to create and give away the source code for a high-quality operating system. By working with the FreeBSD project you can reduce development costs and improve your time to market in a number of product development scenarios.
+The FreeBSD project's goals are to create and give away the source code for a high-quality operating system.
+By working with the FreeBSD project you can reduce development costs and improve your time to market in a number of product development scenarios.
-We examined the characteristics of the FreeBSD project that make it an excellent choice for being part of an organization's product strategy. We then looked at the prevailing culture of the project and examined effective ways of interacting with its developers. The article concluded with a list of best-practices that could help organizations collaborating with the project.
+We examined the characteristics of the FreeBSD project that make it an excellent choice for being part of an organization's product strategy.
+We then looked at the prevailing culture of the project and examined effective ways of interacting with its developers.
+The article concluded with a list of best-practices that could help organizations collaborating with the project.
:sectnums!:
diff --git a/documentation/content/en/articles/committers-guide/_index.adoc b/documentation/content/en/articles/committers-guide/_index.adoc
index 5e8e39441f..8237c47680 100644
--- a/documentation/content/en/articles/committers-guide/_index.adoc
+++ b/documentation/content/en/articles/committers-guide/_index.adoc
@@ -2,7 +2,7 @@
title: Committer's Guide
authors:
- author: The FreeBSD Documentation Project
-copyright: 1999-2019 The FreeBSD Documentation Project
+copyright: 1999-2021 The FreeBSD Documentation Project
releaseinfo: "$FreeBSD$"
trademarks: ["freebsd", "coverity", "ibm", "intel", "general"]
---
@@ -25,9 +25,13 @@ include::shared/en/urls.adoc[]
[.abstract-title]
Abstract
-This document provides information for the FreeBSD 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.
+This document provides information for the FreeBSD 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 FreeBSD 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 <<non-committers>> for more information.
+Almost all FreeBSD 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 <<non-committers>> for more information.
This document may also be of interest to members of the FreeBSD community who want to learn more about how the project works.
@@ -84,12 +88,15 @@ Useful links:
[[pgpkeys]]
== OpenPGP Keys for FreeBSD
-Cryptographic keys conforming to the OpenPGP (__Pretty Good Privacy__) standard are used by the FreeBSD 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 http://www.nostarch.com/pgp_ml.htm[PGP & GPG: Email for the Practical Paranoid by Michael Lucas] and http://en.wikipedia.org/wiki/Pretty_Good_Privacy[] for more information.
+Cryptographic keys conforming to the OpenPGP (__Pretty Good Privacy__) standard are used by the FreeBSD 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 http://www.nostarch.com/pgp_ml.htm[PGP & GPG: Email for the Practical Paranoid by Michael Lucas] and http://en.wikipedia.org/wiki/Pretty_Good_Privacy[] for more information.
[[pgpkeys-creating]]
=== Creating a Key
-Existing keys can be used, but should be checked with [.filename]#documentation/tools/checkkey.sh# first. In this case, make sure the key has a FreeBSD user ID.
+Existing keys can be used, but should be checked with [.filename]#documentation/tools/checkkey.sh# first.
+In this case, make sure the key has a FreeBSD user ID.
For those who do not yet have an OpenPGP key, or need a new key to meet FreeBSD security requirements, here we show how to generate one.
@@ -156,17 +163,22 @@ You need a Passphrase to protect your secret key.
<.> 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: http://world.std.com/~reinhold/diceware.html[], http://www.iusmentis.com/security/passphrasefaq/[], http://xkcd.com/936/[], http://en.wikipedia.org/wiki/Passphrase[].
+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: http://world.std.com/~reinhold/diceware.html[], http://www.iusmentis.com/security/passphrasefaq/[], http://xkcd.com/936/[], http://en.wikipedia.org/wiki/Passphrase[].
====
-Protect the private key and passphrase. If either the private key or passphrase may have been compromised or disclosed, immediately notify mailto:accounts at FreeBSD.org[accounts at FreeBSD.org] and revoke the key.
+Protect the private key and passphrase.
+If either the private key or passphrase may have been compromised or disclosed, immediately notify mailto:accounts at FreeBSD.org[accounts at FreeBSD.org] and revoke the key.
Committing the new key is shown in <<commit-steps, Steps for New Committers>>.
[[kerberos-ldap]]
== Kerberos and LDAP web Password for FreeBSD Cluster
-The FreeBSD 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:
+The FreeBSD 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:
* https://bugs.freebsd.org/bugzilla[Bugzilla]
* https://ci.freebsd.org[Jenkins]
@@ -192,13 +204,17 @@ A Kerberos password can also be set manually by logging into `freefall.FreeBSD.o
[NOTE]
====
-Unless the Kerberos-authenticated services of the FreeBSD.org cluster have been used previously, `Client unknown` will be shown. This error means that the `ssh kpasswd.freebsd.org` method shown above must be used first to initialize the Kerberos account.
+Unless the Kerberos-authenticated services of the FreeBSD.org cluster have been used previously, `Client unknown` will be shown.
+This error means that the `ssh kpasswd.freebsd.org` method shown above must be used first to initialize the Kerberos account.
====
[[committer.types]]
== Commit Bit Types
-The FreeBSD 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 FreeBSD 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.
+The FreeBSD 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 FreeBSD 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.
[.informaltable]
[cols="1,1,1", frame="none"]
@@ -221,7 +237,9 @@ The FreeBSD repository has a number of components which, when combined, support
|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.
+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.
@@ -244,17 +262,14 @@ this section is a work in progress...
[[git-basics]]
=== Git basics
-There are many primers on how to use Git on the web. There's a lot of
-them (google "Git primer"). This one comes up first, and is generally
-good. https://danielmiessler.com/study/git/ and
-https://gist.github.com/williewillus/068e9a8543de3a7ef80adb2938657b6b
-are good overviews. The Git book is also complete, but much longer
-https://git-scm.com/book/en/v2. There is also this website
-https://ohshitgit.com/ for common traps and pitfalls of Git, in case
-you need guidance to fix things up.
+There are many primers on how to use Git on the web.
+There's a lot of them (google "Git primer").
+This one comes up first, and is generally good.
+https://danielmiessler.com/study/git/ and https://gist.github.com/williewillus/068e9a8543de3a7ef80adb2938657b6b are good overviews.
+The Git book is also complete, but much longer https://git-scm.com/book/en/v2.
+There is also this website https://ohshitgit.com/ for common traps and pitfalls of Git, in case you need guidance to fix things up.
-This document will assume that you've read through it and will try not
-to belabor the basics (though it will cover them briefly).
+This document will assume that you've read through it and will try not to belabor the basics (though it will cover them briefly).
[[git-mini-primer]]
=== Git Mini Primer
@@ -475,7 +490,6 @@ For users, for most things, there is very little difference.
However, if you have local changes, you can use the same tool to manage them as you use to pull in changes from FreeBSD.
All changes that you have not pushed are local and can easily be modified (git rebase, discussed below does this).
-
===== Keeping local changes
The simplest way to keep local changes (especially trivial ones) is to use 'git stash'.
In its simples form, you use 'git stash' to record the changes (which pushes them onto the stash stack).
@@ -685,9 +699,8 @@ Eventually, when you are ready to commit your work back to main, you can perform
=== MFC (Merge From Current) Procedures
==== Summary
-MFC workflow can be summarized as `git cherry-pick -x` plus git commit
---amend to adjust the commit message. For multiple commits, use `git rebase -i`
-to squash them together and edit the commit message.
+MFC workflow can be summarized as `git cherry-pick -x` plus git commit--amend to adjust the commit message.
+For multiple commits, use `git rebase -i` to squash them together and edit the commit message.
==== Single commit MFC
@@ -697,8 +710,8 @@ to squash them together and edit the commit message.
% git cherry-pick -x $HASH --edit
....
-For MFC commits, for example a vendor import, you would need to specify one parent for cherry-pick
-purposes. Normally, that would be the "first parent" of the branch you are cherry-picking from, so:
+For MFC commits, for example a vendor import, you would need to specify one parent for cherry-pick purposes.
+Normally, that would be the "first parent" of the branch you are cherry-picking from, so:
[source,shell]
....
@@ -706,11 +719,10 @@ purposes. Normally, that would be the "first parent" of the branch you are cher
% git cherry-pick -x $HASH -m 1 --edit
....
-If things go wrong, you'll either need to abort the cherry-pick with `git cherry-pick --abort` or fix it
-up and do a `git cherry-pick --continue`.
+If things go wrong, you'll either need to abort the cherry-pick with `git cherry-pick --abort` or fix it up and do a `git cherry-pick --continue`.
-Once the cherry-pick is finished, push with `git push`. If you get an error due to losing the commit race,
-use `git pull --rebase` and try to push again.
+Once the cherry-pick is finished, push with `git push`.
+If you get an error due to losing the commit race, use `git pull --rebase` and try to push again.
==== MFC to RELENG branch
@@ -764,22 +776,20 @@ Once the MFC is complete, you can delete the temporary branch:
==== MFC a vendor import
-Vendor imports are the only thing in the tree that creates a merge
-commit in the main line. Cherry picking merge commits into stable/XX
-presents an additional difficulty because there are two parents for a
-merge commit. Generally, you'll want the first parent's diff since
-that's the diff to mainline (though there may be some exceptions).
+Vendor imports are the only thing in the tree that creates a merge commit in the main line.
+Cherry picking merge commits into stable/XX presents an additional difficulty because there are two parents for a merge commit.
+Generally, you'll want the first parent's diff since that's the diff to mainline (though there may be some exceptions).
[source,shell]
....
% git cherry-pick -x -m 1 $HASH
....
-is typically what you want. This will tell cherry-pick to apply the correct diff.
+is typically what you want.
+This will tell cherry-pick to apply the correct diff.
-There are some, hopefully, rare cases where it's possible that the
-mainline was merged backwards by the conversion script. Should that be
-the case (and we've not found any yet), you'd change the above to '-m 2'
-to pickup the proper parent. Just do
+There are some, hopefully, rare cases where it's possible that the mainline was merged backwards by the conversion script.
+Should that be the case (and we've not found any yet), you'd change the above to '-m 2' to pickup the proper parent.
+Just do
[source,shell]
....
% git cherry-pick --abort
@@ -800,8 +810,7 @@ using 'git rebase -i' is better.
==== Considerations when MFCing
-When committing source commits to stable and releng branches, we have
-the following goals:
+When committing source commits to stable and releng branches, we have the following goals:
* Clearly mark direct commits distinct from commits that land a change from another branch.
* Avoid introducing known breakage into stable and releng branches.
@@ -813,118 +822,73 @@ With subversion, we used the following practices to achieve these goals:
* Squashing fixup commits into the main commit when merging a change.
* Recording mergeinfo so that `svn mergeinfo --show-revs` worked.
-With Git, we will need to use different strategies to achieve the same
-goals. This document aims to define best practices when merging
-source commits using git that achieve these goals. In general, we aim
-to use git's native support to achieve these goals rather than
-enforcing practices built on subversion's model.
+With Git, we will need to use different strategies to achieve the same goals.
+This document aims to define best practices when merging source commits using git that achieve these goals.
+In general, we aim to use git's native support to achieve these goals rather than enforcing practices built on subversion's model.
-One general note: due to technical differences with Git, we will not
-be using git "merge commits" (created via `git merge`) in stable or
-releng branches. Instead, when this document refers to "merge
-commits", it means a commit originally made to `main` that is
-replicated or "landed" to a stable branch, or a commit from a stable
-branch that is replicated to a releng branch with some varation of
-`git cherry-pick`.
+One general note: due to technical differences with Git, we will not be using git "merge commits" (created via `git merge`) in stable or releng branches.
+Instead, when this document refers to "merge commits", it means a commit originally made to `main` that is replicated or "landed" to a stable branch, or a commit from a stable branch that is replicated to a releng branch with some varation of `git cherry-pick`.
==== Finding Eligible Hashes to MFC
-Git provides some built-in support for this via the `git cherry` and
-`git log --cherry` commands. These commands compare the raw diffs of
-commits (but not other metadata such as log messages) to determine if
-two commits are identical. This works well when each commit from head
-is landed as a single commit to a stable branch, but it falls over if
-multiple commits from main are squashed together as a single commit to
-a stable branch.
+Git provides some built-in support for this via the `git cherry` and `git log --cherry` commands.
+These commands compare the raw diffs of commits (but not other metadata such as log messages) to determine if two commits are identical.
+This works well when each commit from head is landed as a single commit to a stable branch, but it falls over if multiple commits from main are squashed together as a single commit to a stable branch.
There are a few options for resolving this:
-1. We could ban squashing of commits and instead require that committers
- stage all of the fixup / follow-up commits to stable into a single
- push. This would still achieve the goal of stability in stable and
- releng branches since pushes are atomic and users doing a simple pull
- will never end up with a tree that has the main commit without the
- fixup(s). `git bisect` is also able to cope with this model via
- `git bisect skip`.
-
-2. We could adopt a consistent style for describing MFCs and write
- our own tooling to wrap around `git cherry` to determine the list
- of eligible commits. A simple approach here might be to use the
- syntax from `git cherry-pick -x`, but require that a squashed
- commit list all of the hashes (one line per hash) at the end of
- the commit message. Developers could do this by using
- `git cherry-pick -x` of each individual commit into a branch and
- then use `git rebase` to squash the commits down into a single
- commit, but collecting the `-x` annotations at the end of the
- landed commit log.
+1. We could ban squashing of commits and instead require that committers stage all of the fixup / follow-up commits to stable into a single push.
+This would still achieve the goal of stability in stable and releng branches since pushes are atomic and users doing a simple pull will never end up with a tree that has the main commit without the fixup(s).
+`git bisect` is also able to cope with this model via `git bisect skip`.
+
+2. We could adopt a consistent style for describing MFCs and write our own tooling to wrap around `git cherry` to determine the list of eligible commits.
+A simple approach here might be to use the syntax from `git cherry-pick -x`, but require that a squashed commit list all of the hashes (one line per hash) at the end of the commit message.
+Developers could do this by using `git cherry-pick -x` of each individual commit into a branch and then use `git rebase` to squash the commits down into a single commit, but collecting the `-x` annotations at the end of the landed commit log.
==== Commit message standards
===== Marking MFCs
The project has adopted the following practice for marking MFCs:
-* Use the `-x` flag with `git cherry-pick`. This adds a line to the
- commit message that includes the hash of the original commit when
- merging. Since it is added by Git directly, committers do not have
- to manually edit the commit log when merging.
+* Use the `-x` flag with `git cherry-pick`. This adds a line to the commit message that includes the hash of the original commit when merging. Since it is added by Git directly, committers do not have to manually edit the commit log when merging.
When merging multiple commits, keep all the "cherry picked from" lines.
===== Trim Metadata?
-One area that was not clearly documented with subversion (or even CVS)
-is how to format metadata in log messages for MFC commits. Should
-it include the metadata from the original commit unchanged, or should
-it be altered to reflect information about the MFC commit itself?
-
-Historical practice has varied, though some of the variance is by
-field. For example, MFCs that are relevant to a PR generally
-include the PR field in the MFC so that MFC commits are included
-in the bug tracker's audit trail. Other fields are less clear. For
-example, Phabricator shows the diff of the last commit tagged to a
-review, so including Phabricator URLs replaces the `main` commit with
-the landed commits. The list of reviewers is also not clear. If a
-reviewer has approved a change to `main`, does that mean they have
-approved the MFC commit? Is that true if it's identical code only,
-or with merely trivial reworkes? It's clearly not true for more
-extensive reworks. Even for identical code what if the commit doesn't
-conflict but introduces an ABI change? A reviewer may have ok'd a
-commit for `main` due to the ABI breakage but may not approve of
-merging the same commit as-is. One will have to use one's best
-judgement until clear guidelines can be agreed upon.
-
-For MFCs regulated by re@, new metadata fields are added, such as
-the Approved by tag for approved commits. This new metadata will have
-to be added via `git commit --amend` or similar after the original
-commit has been reviewed and approved. We may also want to reserve
-some metadata fields in MFC commits such as Phabricator URLs for use
-by re@ in the future.
+One area that was not clearly documented with subversion (or even CVS) is how to format metadata in log messages for MFC commits.
+Should it include the metadata from the original commit unchanged, or should it be altered to reflect information about the MFC commit itself?
+
+Historical practice has varied, though some of the variance is by field.
+For example, MFCs that are relevant to a PR generally include the PR field in the MFC so that MFC commits are included in the bug tracker's audit trail.
+Other fields are less clear.
+For example, Phabricator shows the diff of the last commit tagged to a review, so including Phabricator URLs replaces the `main` commit with the landed commits.
+The list of reviewers is also not clear.
+If a reviewer has approved a change to `main`, does that mean they have approved the MFC commit? Is that true if it's identical code only, or with merely trivial reworkes? It's clearly not true for more extensive reworks.
+Even for identical code what if the commit doesn't conflict but introduces an ABI change? A reviewer may have ok'd a commit for `main` due to the ABI breakage but may not approve of merging the same commit as-is.
+One will have to use one's best judgement until clear guidelines can be agreed upon.
+
+For MFCs regulated by re@, new metadata fields are added, such as the Approved by tag for approved commits.
+This new metadata will have to be added via `git commit --amend` or similar after the original commit has been reviewed and approved.
+We may also want to reserve some metadata fields in MFC commits such as Phabricator URLs for use by re@ in the future.
Preserving existing metadata provides a very simple workflow.
-Developers can just use `git cherry-pick -x` without having to edit
-the log message.
+Developers can just use `git cherry-pick -x` without having to edit the log message.
-If instead we choose to adjust metadata in MFCs, developers will
-have to edit log messages explicitly via the use of `git cherry-pick
---edit` or `git commit --amend`. However, as compared to svn, at
-least the existing commit message can be pre-populated and metadata
-fields can be added or removed without having to re-enter the entire
-commit message.
+If instead we choose to adjust metadata in MFCs, developers will have to edit log messages explicitly via the use of `git cherry-pick --edit` or `git commit --amend`.
+However, as compared to svn, at least the existing commit message can be pre-populated and metadata fields can be added or removed without having to re-enter the entire commit message.
-The bottom line is that developers will likely need to curate their
-commit message for MFCs that are non-trivial.
+The bottom line is that developers will likely need to curate their commit message for MFCs that are non-trivial.
==== Examples
===== Merging a Single Subversion Commit
-This walks through the process of merging a commit to stable/12 that
-was originally committed to head in Subversion. In this case, the
-original commit is r368685.
+This walks through the process of merging a commit to stable/12 that was originally committed to head in Subversion.
+In this case, the original commit is r368685.
-The first step is to map the Subversion commit to a Git hash. Once
-you have fetched refs/notes/commits, you can pass the revision number
-to `git log --grep`:
+The first step is to map the Subversion commit to a Git hash.
+Once you have fetched refs/notes/commits, you can pass the revision number to `git log --grep`:
[source,shell]
....
@@ -952,10 +916,9 @@ git checkout stable/12
git cherry-pick -x ce8395ecfda2c8e332a2adf9a9432c2e7f35ea81 --edit
....
-Git will invoke the editor. Use this to remove the metadata that only
-applied to the original commit (Phabricator URL and Reviewed by).
-After the editor saves the updated log message, Git completes the
-commit:
+Git will invoke the editor.
+Use this to remove the metadata that only applied to the original commit (Phabricator URL and Reviewed by).
+After the editor saves the updated log message, Git completes the commit:
[source,shell]
....
@@ -1012,12 +975,10 @@ To gitrepo-dev.FreeBSD.org:src.git
===== Merging a Single Subversion Commit with a Conflict
*** 2573 LINES SKIPPED ***
More information about the dev-commits-doc-all
mailing list