From owner-svn-doc-all@FreeBSD.ORG Mon Mar 18 23:18:13 2013 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.FreeBSD.org [8.8.178.115]) by hub.freebsd.org (Postfix) with ESMTP id 3AD2EC2F; Mon, 18 Mar 2013 23:18:13 +0000 (UTC) (envelope-from rodrigc@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) by mx1.freebsd.org (Postfix) with ESMTP id 16E97313; Mon, 18 Mar 2013 23:18:13 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.6/8.14.6) with ESMTP id r2INIDtv036784; Mon, 18 Mar 2013 23:18:13 GMT (envelope-from rodrigc@svn.freebsd.org) Received: (from rodrigc@localhost) by svn.freebsd.org (8.14.6/8.14.5/Submit) id r2INIDj0036782; Mon, 18 Mar 2013 23:18:13 GMT (envelope-from rodrigc@svn.freebsd.org) Message-Id: <201303182318.r2INIDj0036782@svn.freebsd.org> From: Craig Rodrigues Date: Mon, 18 Mar 2013 23:18:13 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r41264 - head/en_US.ISO8859-1/articles/releng X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 18 Mar 2013 23:18:13 -0000 Author: rodrigc (src committer) Date: Mon Mar 18 23:18:12 2013 New Revision: 41264 URL: http://svnweb.freebsd.org/changeset/doc/41264 Log: Take an initial pass at updating the content in this document to more accurately reflect the current procedures of the FreeBSD Release Engineering team. Reviewed by: delphij nwhitehorn Modified: head/en_US.ISO8859-1/articles/releng/article.xml Modified: head/en_US.ISO8859-1/articles/releng/article.xml ============================================================================== --- head/en_US.ISO8859-1/articles/releng/article.xml Mon Mar 18 18:29:18 2013 (r41263) +++ head/en_US.ISO8859-1/articles/releng/article.xml Mon Mar 18 23:18:12 2013 (r41264) @@ -11,7 +11,9 @@ + November 11, 2001. --> + November 2001 BSDCon Europe @@ -74,8 +76,14 @@ The development of &os; is a very open process. &os; is comprised of contributions from thousands of people around the - world. The &os; Project provides anonymous - CVS[1] access to the general public so that + world. The &os; Project provides + Subversion + + + Subversion, + + + access to the general public so that others can have access to log messages, diffs (patches) between development branches, and other productivity enhancements that formal source code management provides. This has been a huge help @@ -83,9 +91,20 @@ think everyone would agree that chaos would soon manifest if write access was opened up to everyone on the Internet. Therefore only a select group of nearly 300 people are given write - access to the CVS repository. These - committers[5] are responsible for the bulk of - &os; development. An elected core-team[6] + access to the Subversion repository. These + committers + + + FreeBSD committers + + + are responsible for the bulk of &os; development. An elected + Core Team + + + &os; Core Team + + of very senior developers provides some level of direction over the project. @@ -94,16 +113,15 @@ for polishing the development system into a production quality release. To solve this dilemma, development continues on two parallel tracks. The main development branch is the - HEAD or trunk of our CVS + HEAD or trunk of our Subversion tree, known as &os;-CURRENT or -CURRENT for short. A more stable branch is maintained, known as &os;-STABLE or -STABLE for short. - Both branches live in a master CVS repository in California and - are replicated via CVSup[2] to mirrors all over the - world. &os;-CURRENT[7] is the bleeding-edge of + Both branches live in a master Subversion repository on a machine + maintained by the &os; Project. + &os;-CURRENT is the bleeding-edge of &os; development where all new changes first enter the system. &os;-STABLE is the development branch from which major releases are made. Changes go into this branch at a different pace, and @@ -117,52 +135,64 @@ class="resource">ftp://ftp.freebsd.org/pub/FreeBSD/snapshots/. The widespread availability of binary release snapshots, and the tendency of our user community to keep up with -STABLE development - with CVSup and make - world[7] helps to keep + with Subversion and make + buildworld + + + Rebuilding "world" + + + helps to keep &os;-STABLE in a very reliable condition even before the quality assurance activities ramp up pending a major release. Bug reports and feature requests are continuously submitted by users throughout the release cycle. Problems reports are entered into our - GNATS[8] database + GNATS database + + + GNATS: The GNU Bug Tracking System + + + through email, the &man.send-pr.1; application, or via the web interface provided at . - + To service our most conservative users, individual release branches were introduced with &os; 4.3. These release branches are created shortly before a final release is made. After the release goes out, only the most critical security fixes and additions are merged onto the release branch. - In addition to source updates via CVS, binary patchkits are + In addition to source updates via Subversion, binary patchkits are available to keep systems on the RELENG_X_Y branches updated. - + What this article describes - + The following sections of this article describe: - + - + The different phases of the release engineering process leading up to the actual system build. - + - + The actual build process. - + @@ -170,7 +200,7 @@ How the base release may be extended by third parties. - + @@ -264,42 +294,38 @@ Creating the Release Branch - As described in the introduction, the - RELENG_X_Y - release branch is a relatively new addition to our release - engineering - methodology. The first step in creating this branch is to - ensure that you are working with the newest version of the - RELENG_X sources - that you want to branch from. - - /usr/src&prompt.root; cvs update -rRELENG_4 -P -d + + In all examples below, $FSVN + refers to the location of the &os; Subversion repository, + svn+ssh://svn.freebsd.org/base/. + - The next step is to create a branch point - tag, so that diffs against the start of - the branch are easier with CVS: + The layout of &os; branches in Subversion is + described in the Committer's Guide. + The first step in creating a branch is to + identify the revision of the + stable/X sources + that you want to branch from. - /usr/src&prompt.root; cvs rtag -rRELENG_4 RELENG_4_8_BP src + &prompt.root; svn log -v $FSVN/stable/9 - And then a new branch tag is created with: + The next step is to create the release branch + + + &prompt.root; svn cp $FSVN/stable/9@REVISION $FSVN/releng/9.2 - /usr/src&prompt.root; cvs rtag -b -rRELENG_4_8_BP RELENG_4_8 src + This branch can be checked out: + + &prompt.root; svn co $FSVN/releng/9.2 src - The - RELENG_* tags - are restricted for use by the CVS-meisters and release - engineers. + Creating releng branch and release + tags are restricted to + Subversion administrators + and the Release Engineering Team. + - - A tag is CVS - vernacular for a label that identifies the source at a specific point - in time. By tagging the tree, we ensure that future release builders - will always be able to use the same source we used to create the - official &os; Project releases. - - @@ -479,7 +505,14 @@ Sysinstall should be updated to note the number of available ports and the amount of disk space required - for the Ports Collection[4]. This information is currently kept in + for the Ports Collection. + + + &os; Ports Collection + + + + This information is currently kept in src/usr.sbin/sysinstall/dist.c. After the release has been built, a number of file should @@ -526,47 +559,29 @@ - - Preparing a new major release branch - (RELENG_<replaceable>X</replaceable>) - - When a new major release branch, such as - RELENG_6 is branched from HEAD, some - additional files must be updated before releases can be made - from this new branch. - - - - src/share/examples/cvsup/stable-supfile -- must be updated to point to the new -STABLE branch, when -applicable. - - - - - - Creating Release Tags + Creating the Release Tag When the final release is ready, the following command - will create the RELENG_4_8_0_RELEASE + will create the release/9.2.0 tag. - /usr/src&prompt.root; cvs rtag -rRELENG_4_8 RELENG_4_8_0_RELEASE src + &prompt.root; svn cp $FSVN/releng/9.2 $FSVN/release/9.2.0 The Documentation and Ports managers are responsible for - tagging the respective trees with the RELEASE_4_8_0 + tagging their respective trees with the tags/RELEASE_9_2_0 tag. - Occasionally, a last minute fix may be required - after the final tags have been created. - In practice this is not a problem, since CVS - allows tags to be manipulated with cvs - tag -d tagname filename. - It is very important that any last minute changes be tagged - appropriately as part of the release. &os; releases must - always be reproducible. Local hacks in the release - engineer's environment are not acceptable. + + When the Subversion svn cp command + is used to create a release tag, + this identifies the source at a specific point in time. + By creating tags, we ensure that future release builders + will always be able to use the exact same source we used to create the + official &os; Project releases. + + + @@ -577,79 +592,38 @@ applicable. &os; releases can be built by anyone with a fast machine and access to a source repository. (That should be - everyone, since we offer anonymous CVS! See The Handbook for + everyone, since we offer Subversion access ! + See the + Subversion section + in the Handbook for details.) The only special requirement is that the &man.md.4; device must be available. If the device is not loaded into your kernel, then the kernel module should be automatically loaded when &man.mdconfig.8; is executed during the boot media creation phase. All of the tools necessary - to build a release are available from the CVS repository in + to build a release are available from the Subversion repository in src/release. These tools aim to provide a consistent way to build &os; releases. A complete release can actually be built with only a single command, including the creation of ISO images suitable for burning to - CDROM, installation floppies, and an FTP install directory. This - command is aptly named make - release. + CDROM or DVD, and an FTP install directory. &man.release.7; fully + documents the src/release/generate-release.sh + script which is used to build a release. generate-release.sh + is a wrapper around the Makefile target: make release. - <command>make release</command> - - To successfully build a release, you must first populate - /usr/obj by running make - world or simply - make - buildworld. The release - target requires several variables be set properly to build a - release: + Building a Release - - - CHROOTDIR - The directory to be used as the - chroot environment for the entire release build. - - - - BUILDNAME - The name of the release to be - built. - - - - CVSROOT - The location of a CVS Repository. - - - - - RELEASETAG - The CVS tag corresponding to the - release you would like to build. - - - - If you do not already have access to a local CVS - repository, then you may mirror one with CVSup. - The supplied supfile, - /usr/share/examples/cvsup/cvs-supfile, is - a useful starting point for mirroring the CVS - repository. - - If RELEASETAG is omitted, then the - release will be built from the HEAD (aka -CURRENT) branch. - Releases built from this branch are normally referred to as - -CURRENT snapshots. - - There are many other variables available to customize the - release build. Most of these variables are documented at the - top of src/release/Makefile. The exact - command used to build the official &os; 4.7 (x86) release - was: - - make release CHROOTDIR=/local3/release \ - BUILDNAME=4.7-RELEASE \ - CVSROOT=/host/cvs/usr/home/ncvs \ - RELEASETAG=RELENG_4_7_0_RELEASE - - + &man.release.7; documents the exact commands required to + build a &os; release. The following sequences of commands can build + an 9.2.0 release: + + &prompt.root; cd /usr/src/release + &prompt.root; sh generate-release.sh release/9.2.0 /local3/release + + After running these commands, all prepared release + files are available in /local3/release/R + directory. The release Makefile can be broken down into several distinct steps. @@ -663,7 +637,7 @@ applicable. - Checkout from CVS of a clean version of the system source, + Checkout from Subversion of a clean version of the system source, documentation, and ports into the release build hierarchy. @@ -709,20 +683,11 @@ applicable. - Build of the crunched binaries used for - installation floppies. - - - Package up distribution tarballs of the binaries and sources. - Create the boot media and a fixit floppy. - - - Create FTP installation hierarchy. @@ -952,63 +917,19 @@ applicable. be expected to answer questions about it. - Creating Customized Boot floppies - - Many sites have complex requirements that may require - additional kernel modules or userland tools be added to the - installation floppies. The quick and dirty way - to accomplish this would be to modify the staging directory of - an existing make release build hierarchy: - - - - Apply patches or add additional files inside the chroot - release build directory. - - - - rm - ${CHROOTDIR}/usr/obj/usr/src/release/release.[59] - - - - rebuild &man.sysinstall.8;, the kernel, or whatever - parts of the system your change affected. - - - - chroot ${CHROOTDIR} ./mk floppies - - - - - - New release floppies will be located in - ${CHROOTDIR}/R/stage/floppies. - - Alternatively, the - boot.flp make - target can be called, or the filesystem - creating script, - src/release/scripts/doFS.sh, may be invoked - directly. - - Local patches may also be supplied to the release build by - defining the LOCAL_PATCH variable in make - release. - - - - Scripting <command>sysinstall</command> The &os; system installation and configuration tool, &man.sysinstall.8;, can be scripted to provide automated installs for large sites. This functionality can be used in conjunction - with &intel; PXE[12] to bootstrap systems from the network, or - via custom boot floppies with a sysinstall script. An example - sysinstall script is available in the CVS tree as - src/usr.sbin/sysinstall/install.cfg. + with &intel; PXE + + + + + + to bootstrap systems from the network. + @@ -1100,59 +1021,31 @@ applicable. community. I would also like to thank &a.rgrimes;, &a.phk;, and others who worked on the release engineering tools in the very early days of &os;. This article was influenced by release engineering - documents from the CSRG[13], the NetBSD Project[10], and John - Baldwin's proposed release engineering process notes[11]. - - - - - References - [1] CVS - Concurrent Versions System - - - [2] CVSup - The CVS-Optimized General Purpose Network File Distribution - System - - - [3] - - [4] &os; Ports Collection - - - [5] &os; Committers - - - [6] &os; Core Team - - - [7] &os; Handbook - - - - [8] GNATS: The GNU Bug Tracking System - - - - [9] &os; PR Statistics - - - [10] NetBSD Developer Documentation: Release Engineering - - - - [11] John Baldwin's &os; Release Engineering Proposal - - - - [12] PXE Jumpstart Guide - - - - [13] Marshall Kirk McKusick, Michael J. Karels, and Keith Bostic: - -The Release Engineering of 4.3BSD + documents from the CSRG + + + Marshall Kirk McKusick, Michael J. Karels, and Keith Bostic: + + The Release Engineering of 4.3BSD + + + , + the NetBSD Project , + + + NetBSD Developer Documentation: Release Engineering + + + + , and John + Baldwin's proposed release engineering process notes. + + + John Baldwin's &os; Release Engineering Proposal + + + +