import-layers/yocto-poky/documentation/ref-manual/ref-release-process.xml - stefanberger/openbmc - Gitiles

 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
 [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >

 <chapter id='ref-release-process'>
 <title>Yocto Project Releases and the Stable Release Process</title>

 <para>
     The Yocto Project release process is predictable and consists of both
     major and minor (point) releases.
     This brief chapter provides information on how releases are named, their
     life cycle, and their stability.
 </para>

 <section id='major-and-minor-release-cadence'>
     <title>Major and Minor Release Cadence</title>

     <para>
         The Yocto Project delivers major releases (e.g. &DISTRO;) using a six
         month cadence roughly timed each April and October of the year.
         Following are examples of some major YP releases with their codenames
         also shown.
         See the
         "<link linkend='major-release-codenames'>Major Release Codenames</link>"
         section for information on codenames used with major releases.
         <literallayout class='monospaced'>
     2.2 (Morty)
     2.1 (Krogoth)
     2.0 (Jethro)
         </literallayout>
         While the cadence is never perfect, this timescale facilitates
         regular releases that have strong QA cycles while not overwhelming
         users with too many new releases.
         The cadence is predictable and avoids many major holidays in various
         geographies.
     </para>

     <para>
         The Yocto project delivers minor (point) releases on an unscheduled
         basis and are usually driven by the accumulation of enough significant
         fixes or enhancements to the associated major release.
         Following are some example past point releases:
         <literallayout class='monospaced'>
     2.1.1
     2.1.2
     2.2.1
         </literallayout>
         The point release indicates a point in the major release branch where
         a full QA cycle and release process validates the content of the new
         branch.
         <note>
             Realize that there can be patches merged onto the stable release
             branches as and when they become available.
         </note>
     </para>
 </section>

 <section id='major-release-codenames'>
     <title>Major Release Codenames</title>

     <para>
         Each major release receives a codename that identifies the release in
         the
         <ulink url='&YOCTO_DOCS_DEV_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>.
         The concept is that branches of
         <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
         with the same codename are likely to be compatible and thus
         work together.
         <note>
             Codenames are associated with major releases because a Yocto
             Project release number (e.g. &DISTRO;) could conflict with
             a given layer or company versioning scheme.
             Codenames are unique, interesting, and easily identifiable.
         </note>
         Releases are given a nominal release version as well but the codename
         is used in repositories for this reason.
         You can find information on Yocto Project releases and codenames at
         <ulink url='https://wiki.yoctoproject.org/wiki/Releases'></ulink>.
     </para>
 </section>

 <section id='stable-release-process'>
     <title>Stable Release Process</title>

     <para>
         Once released, the release enters the stable release process at which
         time a person is assigned as the maintainer for that stable release.
         This maintainer monitors activity for the release by investigating
         and handling nominated patches and backport activity.
         Only fixes and enhancements that have first been applied on the
         "master" branch (i.e. the current, in-development branch) are
         considered for backporting to a stable release.
         <note>
             The current Yocto Project policy regarding backporting is to
             consider bug fixes and security fixes only.
             Policy dictates that features are not backported to a stable
             release.
             This policy means generic recipe version upgrades are unlikely to
             be accepted for backporting.
             The exception to this policy occurs when a strong reason exists
             such as the fix happens to also be the preferred upstream approach.
         </note>
     </para>

     <para>
         Stable release branches have strong maintenance for about a year after
         their initial release.
         Should significant issues be found for any release regardless of its
         age, fixes could be backported to older releases.
         For issues that are not backported given an older release,
         Community LTS trees and branches exist where
         community members share patches for older releases.
         However, these types of patches do not go through the same release
         process as do point releases.
         You can find more information about stable branch maintenance at
         <ulink url='https://wiki.yoctoproject.org/wiki/Stable_branch_maintenance'></ulink>.
     </para>
 </section>

 <section id='testing-and-quality-assurance'>
     <title>Testing and Quality Assurance</title>

     <para>
         Part of the Yocto Project development and release process is quality
         assurance through the execution of test strategies.
         Test strategies provide the Yocto Project team a way to ensure a
         release is validated.
         Additionally, because the test strategies are visible to you as a
         developer, you can validate your projects.
         This section overviews the available test infrastructure used in the
         Yocto Project.
         For information on how to run available tests on your projects, see the
         "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
         section in the Yocto Project Development Manual.
     </para>

     <para>
         The QA/testing infrastructure is woven into the project to the point
         where core developers take some of it for granted.
         The infrastructure consists of the following pieces:
         <itemizedlist>
             <listitem><para>
                 <filename>bitbake-selftest</filename>:
                 A standalone command that runs unit tests on key pieces of
                 BitBake and its fetchers.
                 </para></listitem>
             <listitem><para>
                 <link linkend='ref-classes-sanity'><filename>sanity.bbclass</filename></link>:
                 This automatically included class checks the build environment
                 for missing tools (e.g. <filename>gcc</filename>) or common
                 misconfigurations such as
                 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
                 set incorrectly.
                 </para></listitem>
             <listitem><para>
                 <link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>:
                 This class checks the generated output from builds for sanity.
                 For example, if building for an ARM target, did the build
                 produce ARM binaries.
                 If, for example, the build produced PPC binaries then there
                 is a problem.
                 </para></listitem>
             <listitem><para>
                 <link linkend='ref-classes-testimage*'><filename>testimage.bbclass</filename></link>:
                 This class performs runtime testing of images after they are
                 built.
                 The tests are usually used with
                 <ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>QEMU</ulink>
                 to boot the images and check the combined runtime result
                 boot operation and functions.
                 However, the test can also use the IP address of a machine to
                 test.
                 </para></listitem>
             <listitem><para>
                 <ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'><filename>ptest</filename></ulink>:
                 Runs tests against packages produced during the build for a
                 given piece of software.
                 The test allows the packages to be be run within a target
                 image.
                 </para></listitem>
             <listitem><para>
                 <filename>oe-selftest</filename>:
                 Tests combination BitBake invocations.
                 These tests operate outside the OpenEmbedded build system
                 itself.
                 The <filename>oe-selftest</filename> can run all tests by
                 default or can run selected tests or test suites.
                 <note>
                     Running <filename>oe-selftest</filename> requires
                     host packages beyond the "Essential" grouping.
                     See the
                     "<link linkend='required-packages-for-the-host-development-system'>Required Packages for the Host Development System</link>"
                     section for more information.
                 </note>
                 </para></listitem>
         </itemizedlist>
     </para>

     <para>
         Originally, much of this testing was done manually.
         However, significant effort has been made to automate the tests so
         that more people can use them and the Yocto Project development team
         can run them faster and more efficiently.
     </para>

     <para>
         The Yocto Project's main Autobuilder
         (<filename>autobuilder.yoctoproject.org</filename>) publicly tests
         each Yocto Project release's code in the OE-Core, Poky, and BitBake
         repositories.
         The testing occurs for both the current state of the
         "master" branch and also for submitted patches.
         Testing for submitted patches usually occurs in the
         "ross/mut" branch in the <filename>poky-contrib</filename> repository
         (i.e. the master-under-test branch) or in the "master-next" branch
         in the <filename>poky</filename> repository.
         <note>
             You can find all these branches in the Yocto Project
             <ulink url='&YOCTO_DOCS_DEV_URL;#source-repositories'>Source Repositories</ulink>.
         </note>
         Testing within these public branches ensures in a publicly visible way
         that all of the main supposed architectures and recipes in OE-Core
         successfully build and behave properly.
     </para>

     <para>
         Various features such as <filename>multilib</filename>, sub
         architectures (e.g. <filename>x32</filename>,
         <filename>poky-tiny</filename>, <filename>musl</filename>,
         <filename>no-x11</filename> and and so forth),
         <filename>bitbake-selftest</filename>, and
         <filename>oe-selftest</filename> are tested as part of
         the QA process of a release.
         Complete testing and validation for a release takes the Autobuilder
         workers several hours.
         <note>
             The Autobuilder workers are non-homogeneous, which means regular
             testing across a variety of Linux distributions occurs.
             The Autobuilder is limited to only testing QEMU-based setups and
             not real hardware.
         </note>
     </para>

     <para>
         Finally, in addition to the Autobuilder's tests, the Yocto Project
         QA team also performs testing on a variety of platforms, which includes
         actual hardware, to ensure expected results.
     </para>
 </section>

 </chapter>
 <!--
 vim: expandtab tw=80 ts=4
 -->
	<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
	[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >

	<chapter id='ref-release-process'>
	<title>Yocto Project Releases and the Stable Release Process</title>

	<para>
	The Yocto Project release process is predictable and consists of both
	major and minor (point) releases.
	This brief chapter provides information on how releases are named, their
	life cycle, and their stability.
	</para>

	<section id='major-and-minor-release-cadence'>
	<title>Major and Minor Release Cadence</title>

	<para>
	The Yocto Project delivers major releases (e.g. &DISTRO;) using a six
	month cadence roughly timed each April and October of the year.
	Following are examples of some major YP releases with their codenames
	also shown.
	See the
	"<link linkend='major-release-codenames'>Major Release Codenames</link>"
	section for information on codenames used with major releases.
	<literallayout class='monospaced'>
	2.2 (Morty)
	2.1 (Krogoth)
	2.0 (Jethro)
	</literallayout>
	While the cadence is never perfect, this timescale facilitates
	regular releases that have strong QA cycles while not overwhelming
	users with too many new releases.
	The cadence is predictable and avoids many major holidays in various
	geographies.
	</para>

	<para>
	The Yocto project delivers minor (point) releases on an unscheduled
	basis and are usually driven by the accumulation of enough significant
	fixes or enhancements to the associated major release.
	Following are some example past point releases:
	<literallayout class='monospaced'>
	2.1.1
	2.1.2
	2.2.1
	</literallayout>
	The point release indicates a point in the major release branch where
	a full QA cycle and release process validates the content of the new
	branch.
	<note>
	Realize that there can be patches merged onto the stable release
	branches as and when they become available.
	</note>
	</para>
	</section>

	<section id='major-release-codenames'>
	<title>Major Release Codenames</title>

	<para>
	Each major release receives a codename that identifies the release in
	the
	<ulink url='&YOCTO_DOCS_DEV_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>.
	The concept is that branches of
	<ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
	with the same codename are likely to be compatible and thus
	work together.
	<note>
	Codenames are associated with major releases because a Yocto
	Project release number (e.g. &DISTRO;) could conflict with
	a given layer or company versioning scheme.
	Codenames are unique, interesting, and easily identifiable.
	</note>
	Releases are given a nominal release version as well but the codename
	is used in repositories for this reason.
	You can find information on Yocto Project releases and codenames at
	<ulink url='https://wiki.yoctoproject.org/wiki/Releases'></ulink>.
	</para>
	</section>

	<section id='stable-release-process'>
	<title>Stable Release Process</title>

	<para>
	Once released, the release enters the stable release process at which
	time a person is assigned as the maintainer for that stable release.
	This maintainer monitors activity for the release by investigating
	and handling nominated patches and backport activity.
	Only fixes and enhancements that have first been applied on the
	"master" branch (i.e. the current, in-development branch) are
	considered for backporting to a stable release.
	<note>
	The current Yocto Project policy regarding backporting is to
	consider bug fixes and security fixes only.
	Policy dictates that features are not backported to a stable
	release.
	This policy means generic recipe version upgrades are unlikely to
	be accepted for backporting.
	The exception to this policy occurs when a strong reason exists
	such as the fix happens to also be the preferred upstream approach.
	</note>
	</para>

	<para>
	Stable release branches have strong maintenance for about a year after
	their initial release.
	Should significant issues be found for any release regardless of its
	age, fixes could be backported to older releases.
	For issues that are not backported given an older release,
	Community LTS trees and branches exist where
	community members share patches for older releases.
	However, these types of patches do not go through the same release
	process as do point releases.
	You can find more information about stable branch maintenance at
	<ulink url='https://wiki.yoctoproject.org/wiki/Stable_branch_maintenance'></ulink>.
	</para>
	</section>

	<section id='testing-and-quality-assurance'>
	<title>Testing and Quality Assurance</title>

	<para>
	Part of the Yocto Project development and release process is quality
	assurance through the execution of test strategies.
	Test strategies provide the Yocto Project team a way to ensure a
	release is validated.
	Additionally, because the test strategies are visible to you as a
	developer, you can validate your projects.
	This section overviews the available test infrastructure used in the
	Yocto Project.
	For information on how to run available tests on your projects, see the
	"<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
	section in the Yocto Project Development Manual.
	</para>

	<para>
	The QA/testing infrastructure is woven into the project to the point
	where core developers take some of it for granted.
	The infrastructure consists of the following pieces:
	<itemizedlist>
	<listitem><para>
	<filename>bitbake-selftest</filename>:
	A standalone command that runs unit tests on key pieces of
	BitBake and its fetchers.
	</para></listitem>
	<listitem><para>
	<link linkend='ref-classes-sanity'><filename>sanity.bbclass</filename></link>:
	This automatically included class checks the build environment
	for missing tools (e.g. <filename>gcc</filename>) or common
	misconfigurations such as
	<link linkend='var-MACHINE'><filename>MACHINE</filename></link>
	set incorrectly.
	</para></listitem>
	<listitem><para>
	<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>:
	This class checks the generated output from builds for sanity.
	For example, if building for an ARM target, did the build
	produce ARM binaries.
	If, for example, the build produced PPC binaries then there
	is a problem.
	</para></listitem>
	<listitem><para>
	<link linkend='ref-classes-testimage*'><filename>testimage.bbclass</filename></link>:
	This class performs runtime testing of images after they are
	built.
	The tests are usually used with
	<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>QEMU</ulink>
	to boot the images and check the combined runtime result
	boot operation and functions.
	However, the test can also use the IP address of a machine to
	test.
	</para></listitem>
	<listitem><para>
	<ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'><filename>ptest</filename></ulink>:
	Runs tests against packages produced during the build for a
	given piece of software.
	The test allows the packages to be be run within a target
	image.
	</para></listitem>
	<listitem><para>
	<filename>oe-selftest</filename>:
	Tests combination BitBake invocations.
	These tests operate outside the OpenEmbedded build system
	itself.
	The <filename>oe-selftest</filename> can run all tests by
	default or can run selected tests or test suites.
	<note>
	Running <filename>oe-selftest</filename> requires
	host packages beyond the "Essential" grouping.
	See the
	"<link linkend='required-packages-for-the-host-development-system'>Required Packages for the Host Development System</link>"
	section for more information.
	</note>
	</para></listitem>
	</itemizedlist>
	</para>

	<para>
	Originally, much of this testing was done manually.
	However, significant effort has been made to automate the tests so
	that more people can use them and the Yocto Project development team
	can run them faster and more efficiently.
	</para>

	<para>
	The Yocto Project's main Autobuilder
	(<filename>autobuilder.yoctoproject.org</filename>) publicly tests
	each Yocto Project release's code in the OE-Core, Poky, and BitBake
	repositories.
	The testing occurs for both the current state of the
	"master" branch and also for submitted patches.
	Testing for submitted patches usually occurs in the
	"ross/mut" branch in the <filename>poky-contrib</filename> repository
	(i.e. the master-under-test branch) or in the "master-next" branch
	in the <filename>poky</filename> repository.
	<note>
	You can find all these branches in the Yocto Project
	<ulink url='&YOCTO_DOCS_DEV_URL;#source-repositories'>Source Repositories</ulink>.
	</note>
	Testing within these public branches ensures in a publicly visible way
	that all of the main supposed architectures and recipes in OE-Core
	successfully build and behave properly.
	</para>

	<para>
	Various features such as <filename>multilib</filename>, sub
	architectures (e.g. <filename>x32</filename>,
	<filename>poky-tiny</filename>, <filename>musl</filename>,
	<filename>no-x11</filename> and and so forth),
	<filename>bitbake-selftest</filename>, and
	<filename>oe-selftest</filename> are tested as part of
	the QA process of a release.
	Complete testing and validation for a release takes the Autobuilder
	workers several hours.
	<note>
	The Autobuilder workers are non-homogeneous, which means regular
	testing across a variety of Linux distributions occurs.
	The Autobuilder is limited to only testing QEMU-based setups and
	not real hardware.
	</note>
	</para>

	<para>
	Finally, in addition to the Autobuilder's tests, the Yocto Project
	QA team also performs testing on a variety of platforms, which includes
	actual hardware, to ensure expected results.
	</para>
	</section>

	</chapter>
	<!--
	vim: expandtab tw=80 ts=4
	-->