1 files changed, 211 insertions, 49 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index e9555e6168..479362fca5 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -1974,71 +1974,233 @@
            </itemizedlist>
        </para>
-        <section id="usingpoky-changes-prbump">
+        <section id='incrementing-a-package-revision-number'>
            <title>Incrementing a Package Revision Number</title>
            <para>
                If a committed change results in changing the package output,
                then the value of the
-                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink></filename>
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
-                variable needs to be increased
+                variable needs to be increased (or "bumped").
-                (or "bumped") as part of that commit.
+                Increasing <filename>PR</filename> occurs one of two ways:
-                For new recipes you should add the <filename>PR</filename>
+                <itemizedlist>
-                variable and set its initial value equal to "r0", which is the default.
+                    <listitem><para>Automatically using a Package Revision
-                Even though the default value is "r0", the practice of adding it to a new recipe makes
+                        Service (PR Service).</para></listitem>
-                it harder to forget to bump the variable when you make changes
+                    <listitem><para>Manually incrementing the
-                to the recipe in future.
+                        <filename>PR</filename> variable.</para></listitem>
+                </itemizedlist>
            </para>
            <para>
-                If you are sharing a common <filename>.inc</filename> file with multiple recipes,
+                Given that one of the challenges any build system and its
-                you can also use the
+                users face is how to maintain a package feed that is compatible
-                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-INC_PR'>INC_PR</ulink></filename>
+                with existing package manager applications such as
-                variable to ensure that
+                RPM, APT, and OPKG, using an automated system is much
-                the recipes sharing the <filename>.inc</filename> file are rebuilt when the
+                preferred over a manual system.
-                <filename>.inc</filename> file itself is changed.
+                In either system, the main requirement is that version
-                The <filename>.inc</filename> file must set <filename>INC_PR</filename>
+                numbering increases in a linear fashion and that a number of
-                (initially to "r0"), and all recipes referring to it should set <filename>PR</filename>
+                version components exist that support that linear progression.
-                to "$(INC_PR).0" initially, incrementing the last number when the recipe is changed.
-                If the <filename>.inc</filename> file is changed then its
-                <filename>INC_PR</filename> should be incremented.
            </para>
            <para>
-                When upgrading the version of a package, assuming the
+                The following two sections provide information on the PR Service
-                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'>PV</ulink></filename>
+                and on manual <filename>PR</filename> bumping.
-                changes, the <filename>PR</filename> variable should be reset to "r0"
-                (or "$(INC_PR).0" if you are using <filename>INC_PR</filename>).
            </para>
-            <para>
+            <section id='working-with-a-pr-service'>
-                Usually, version increases occur only to packages.
+                <title>Working With a PR Service</title>
-                However, if for some reason <filename>PV</filename> changes but does not
-                increase, you can increase the
-                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PE'>PE</ulink></filename>
-                variable (Package Epoch).
-                The <filename>PE</filename> variable defaults to "0".
-            </para>
-            <para>
+                <para>
-                Version numbering strives to follow the
+                    As mentioned, attempting to maintain revision numbers in the
-                <ulink url='http://www.debian.org/doc/debian-policy/ch-controlfields.html'>
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
-                Debian Version Field Policy Guidelines</ulink>.
+                    is error prone, inaccurate and causes problems for people
-                These guidelines define how versions are compared and what "increasing" a version means.
+                    submitting recipes.
-            </para>
+                    Conversely, the PR Service automatically generates
+                    increasing numbers, particularly the revision field,
+                    which removes the human element.
+                    <note>
+                        For additional information on using a PR Service, you
+                        can see the
+                        <ulink url='&YOCTO_WIKI_URL;/wiki/PR_Service'>PR Service</ulink>
+                        wiki page.
+                    </note>
+                </para>
-            <para>
+                <para>
-                There are two reasons for following the previously mentioned guidelines.
+                    The Yocto Project uses variables in order of
-                First, to ensure that when a developer updates and rebuilds, they get all the changes to
+                    decreasing priority to facilitate revision numbering (i.e.
-                the repository and do not have to remember to rebuild any sections.
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>,
-                Second, to ensure that target users are able to upgrade their
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>, and
-                devices using package manager commands such as <filename>opkg upgrade</filename>
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
-                (or similar commands for dpkg/apt or rpm-based systems).
+                    for epoch, version and revision, respectively).
-            </para>
+                    The values are highly dependent on the policies and
+                    procedures of a given distribution and package feed.
+                </para>
-            <para>
+                <para>
-                The goal is to ensure the Yocto Project has packages that can be upgraded in all cases.
+                    Because the OpenEmbedded build system uses "signatures",
-            </para>
+                    which are unique to a given build, the build system
+                    knows when to rebuild packages.
+                    All the inputs into a given task are represented by a
+                    signature, which can trigger a rebuild when different.
+                    Thus, the build system itself does not rely on the
+                    <filename>PR</filename> numbers to trigger a rebuild.
+                    The signatures, however, can be used to generate
+                    <filename>PR</filename> values.
+                </para>
+                <para>
+                    The PR Service works with both
+                    <filename>OEBasic</filename> and
+                    <filename>OEBasicHash</filename> generators.
+                    The value of <filename>PR</filename> bumps when the
+                    checksum changes and the different generator mechanisms
+                    change signatures under different circumstances.
+                </para>
+                <para>
+                    As implemented, the build system includes values from
+                    the PR Service into the <filename>PR</filename> field as
+                    an addition using the form "<filename>.x</filename>" so
+                    <filename>r0</filename> becomes <filename>r0.1</filename>,
+                    <filename>r0.2</filename> and so forth.
+                    This scheme allows existing <filename>PR</filename> values
+                    to be used for whatever reasons, which include manual
+                    <filename>PR</filename> bumps should it be necessary.
+                </para>
+                <para>
+                    By default, there is no server that runs the PR Service.
+                    Thus, the packages generated are just "self consistent".
+                    The build system adds and removes packages and
+                    there are no guarantees about upgrade paths.
+                </para>
+                <para>
+                    The simplest form for a PR Service is for it to exist
+                    for a single host development system that builds the
+                    package feed (building system).
+                    For this scenario, you can enable the PR Service by adding
+                    the following to your <filename>local.conf</filename>
+                    file in the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
+                    <literallayout class='monospaced'>
+     PRSERV_HOST = "localhost:0"
+                    </literallayout>
+                    Once the service is started, packages will automatically
+                    get increasing <filename>PR</filename> values and
+                    BitBake will take care of starting and stopping the server.
+                </para>
+                <para>
+                    If you have a more complex setup where multiple host
+                    development systems work against a common, shared package
+                    feed, you have a single PR Service running and it is
+                    connected to each building system.
+                    For this scenario, you need to start the PR Service using
+                    the <filename>bitbake-prserv</filename> command:
+                    <literallayout class='monospaced'>
+     bitbake-prserve &dash;&dash;host &lt;ip&gt; &dash;&dash;port &lt;port&gt; &dash;&dash;start
+                    </literallayout>
+                    In addition to hand-starting the service, you need to
+                    update the <filename>local.conf</filename> file of each
+                    building system as described earlier so each system
+                    points to the server and port.
+                </para>
+                <para>
+                    It is also recommended you use build history, which adds
+                    some sanity checks to package versions, in conjunction with
+                    the server that is running the PR Service.
+                    To enable build history, add the following to each building
+                    system's <filename>local.conf</filename> file:
+                    <literallayout class='monospaced'>
+     # It is recommended to activate "buildhistory" for testing the PR service
+     INHERIT += "buildhistory"
+     BUILDHISTORY_COMMIT = "1"
+                    </literallayout>
+                    For information on build history, see the
+                    "<ulink url='&YOCTO_DOCS_REF_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
+                    section in the Yocto Project Reference Manual.
+                </para>
+                <note>
+                    The OpenEmbedded build system does not maintain
+                    <filename>PR</filename> information as part of the
+                    shared state (sstate) packages.
+                    If you maintain an sstate feed, its expected that either
+                    all your building systems that contribute to the sstate
+                    feed use a shared PR Service, or you do not run a PR
+                    Service on any of your building systems.
+                    Having some systems use a PR Service while others do
+                    not leads to obvious problems.
+                </note>
+            </section>
+            <section id='manually-bumping-pr'>
+                <title>Manually Bumping PR</title>
+                <para>
+                    If a committed change results in changing the package output,
+                    then the value of the PR variable needs to be increased
+                    (or "bumped") as part of that commit.
+                    For new recipes you should add the <filename>PR</filename>
+                    variable and set its initial value equal to "r0", which is the default.
+                    Even though the default value is "r0", the practice of adding it to a new recipe makes
+                    it harder to forget to bump the variable when you make changes
+                    to the recipe in future.
+                </para>
+                <para>
+                    If you are sharing a common <filename>.inc</filename> file with multiple recipes,
+                    you can also use the
+                    <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-INC_PR'>INC_PR</ulink></filename>
+                    variable to ensure that
+                    the recipes sharing the <filename>.inc</filename> file are rebuilt when the
+                    <filename>.inc</filename> file itself is changed.
+                    The <filename>.inc</filename> file must set <filename>INC_PR</filename>
+                    (initially to "r0"), and all recipes referring to it should set <filename>PR</filename>
+                    to "$(INC_PR).0" initially, incrementing the last number when the recipe is changed.
+                    If the <filename>.inc</filename> file is changed then its
+                    <filename>INC_PR</filename> should be incremented.
+                </para>
+                <para>
+                    When upgrading the version of a package, assuming the
+                    <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'>PV</ulink></filename>
+                    changes, the <filename>PR</filename> variable should be reset to "r0"
+                    (or "$(INC_PR).0" if you are using <filename>INC_PR</filename>).
+                </para>
+                <para>
+                    Usually, version increases occur only to packages.
+                    However, if for some reason <filename>PV</filename> changes but does not
+                    increase, you can increase the
+                    <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PE'>PE</ulink></filename>
+                    variable (Package Epoch).
+                    The <filename>PE</filename> variable defaults to "0".
+                </para>
+                <para>
+                    Version numbering strives to follow the
+                    <ulink url='http://www.debian.org/doc/debian-policy/ch-controlfields.html'>
+                    Debian Version Field Policy Guidelines</ulink>.
+                    These guidelines define how versions are compared and what "increasing" a version means.
+                </para>
+                <para>
+                    There are two reasons for following the previously mentioned guidelines.
+                    First, to ensure that when a developer updates and rebuilds, they get all the changes to
+                    the repository and do not have to remember to rebuild any sections.
+                    Second, to ensure that target users are able to upgrade their
+                    devices using package manager commands such as <filename>opkg upgrade</filename>
+                    (or similar commands for dpkg/apt or rpm-based systems).
+                </para>
+                <para>
+                    The goal is to ensure the Yocto Project has packages that can be upgraded in all cases.
+                </para>
+            </section>
        </section>
        <section id="usingpoky-configuring-DISTRO_PN_ALIAS">

diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index e9555e6168..479362fca5 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -1974,71 +1974,233 @@
1974	</itemizedlist>	1974	</itemizedlist>
1975	</para>	1975	</para>
1976		1976
1977	<section id="usingpoky-changes-prbump">	1977	<section id='incrementing-a-package-revision-number'>
1978	<title>Incrementing a Package Revision Number</title>	1978	<title>Incrementing a Package Revision Number</title>
1979		1979
1980	<para>	1980	<para>
1981	If a committed change results in changing the package output,	1981	If a committed change results in changing the package output,
1982	then the value of the	1982	then the value of the
1983	<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink></filename>	1983	<ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
1984	variable needs to be increased	1984	variable needs to be increased (or "bumped").
1985	(or "bumped") as part of that commit.	1985	Increasing <filename>PR</filename> occurs one of two ways:
1986	For new recipes you should add the <filename>PR</filename>	1986	<itemizedlist>
1987	variable and set its initial value equal to "r0", which is the default.	1987	<listitem><para>Automatically using a Package Revision
1988	Even though the default value is "r0", the practice of adding it to a new recipe makes	1988	Service (PR Service).</para></listitem>
1989	it harder to forget to bump the variable when you make changes	1989	<listitem><para>Manually incrementing the
1990	to the recipe in future.	1990	<filename>PR</filename> variable.</para></listitem>
		1991	</itemizedlist>
1991	</para>	1992	</para>
1992		1993
1993	<para>	1994	<para>
1994	If you are sharing a common <filename>.inc</filename> file with multiple recipes,	1995	Given that one of the challenges any build system and its
1995	you can also use the	1996	users face is how to maintain a package feed that is compatible
1996	<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-INC_PR'>INC_PR</ulink></filename>	1997	with existing package manager applications such as
1997	variable to ensure that	1998	RPM, APT, and OPKG, using an automated system is much
1998	the recipes sharing the <filename>.inc</filename> file are rebuilt when the	1999	preferred over a manual system.
1999	<filename>.inc</filename> file itself is changed.	2000	In either system, the main requirement is that version
2000	The <filename>.inc</filename> file must set <filename>INC_PR</filename>	2001	numbering increases in a linear fashion and that a number of
2001	(initially to "r0"), and all recipes referring to it should set <filename>PR</filename>	2002	version components exist that support that linear progression.
2002	to "$(INC_PR).0" initially, incrementing the last number when the recipe is changed.
2003	If the <filename>.inc</filename> file is changed then its
2004	<filename>INC_PR</filename> should be incremented.
2005	</para>	2003	</para>
2006		2004
2007	<para>	2005	<para>
2008	When upgrading the version of a package, assuming the	2006	The following two sections provide information on the PR Service
2009	<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'>PV</ulink></filename>	2007	and on manual <filename>PR</filename> bumping.
2010	changes, the <filename>PR</filename> variable should be reset to "r0"
2011	(or "$(INC_PR).0" if you are using <filename>INC_PR</filename>).
2012	</para>	2008	</para>
2013		2009
2014	<para>	2010	<section id='working-with-a-pr-service'>
2015	Usually, version increases occur only to packages.	2011	<title>Working With a PR Service</title>
2016	However, if for some reason <filename>PV</filename> changes but does not
2017	increase, you can increase the
2018	<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PE'>PE</ulink></filename>
2019	variable (Package Epoch).
2020	The <filename>PE</filename> variable defaults to "0".
2021	</para>
2022		2012
2023	<para>	2013	<para>
2024	Version numbering strives to follow the	2014	As mentioned, attempting to maintain revision numbers in the
2025	<ulink url='http://www.debian.org/doc/debian-policy/ch-controlfields.html'>	2015	<ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
2026	Debian Version Field Policy Guidelines</ulink>.	2016	is error prone, inaccurate and causes problems for people
2027	These guidelines define how versions are compared and what "increasing" a version means.	2017	submitting recipes.
2028	</para>	2018	Conversely, the PR Service automatically generates
		2019	increasing numbers, particularly the revision field,
		2020	which removes the human element.
		2021	<note>
		2022	For additional information on using a PR Service, you
		2023	can see the
		2024	<ulink url='&YOCTO_WIKI_URL;/wiki/PR_Service'>PR Service</ulink>
		2025	wiki page.
		2026	</note>
		2027	</para>
2029		2028
2030	<para>	2029	<para>
2031	There are two reasons for following the previously mentioned guidelines.	2030	The Yocto Project uses variables in order of
2032	First, to ensure that when a developer updates and rebuilds, they get all the changes to	2031	decreasing priority to facilitate revision numbering (i.e.
2033	the repository and do not have to remember to rebuild any sections.	2032	<ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>,
2034	Second, to ensure that target users are able to upgrade their	2033	<ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>, and
2035	devices using package manager commands such as <filename>opkg upgrade</filename>	2034	<ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
2036	(or similar commands for dpkg/apt or rpm-based systems).	2035	for epoch, version and revision, respectively).
2037	</para>	2036	The values are highly dependent on the policies and
		2037	procedures of a given distribution and package feed.
		2038	</para>
2038		2039
2039	<para>	2040	<para>
2040	The goal is to ensure the Yocto Project has packages that can be upgraded in all cases.	2041	Because the OpenEmbedded build system uses "signatures",
2041	</para>	2042	which are unique to a given build, the build system
		2043	knows when to rebuild packages.
		2044	All the inputs into a given task are represented by a
		2045	signature, which can trigger a rebuild when different.
		2046	Thus, the build system itself does not rely on the
		2047	<filename>PR</filename> numbers to trigger a rebuild.
		2048	The signatures, however, can be used to generate
		2049	<filename>PR</filename> values.
		2050	</para>
		2051
		2052	<para>
		2053	The PR Service works with both
		2054	<filename>OEBasic</filename> and
		2055	<filename>OEBasicHash</filename> generators.
		2056	The value of <filename>PR</filename> bumps when the
		2057	checksum changes and the different generator mechanisms
		2058	change signatures under different circumstances.
		2059	</para>
		2060
		2061	<para>
		2062	As implemented, the build system includes values from
		2063	the PR Service into the <filename>PR</filename> field as
		2064	an addition using the form "<filename>.x</filename>" so
		2065	<filename>r0</filename> becomes <filename>r0.1</filename>,
		2066	<filename>r0.2</filename> and so forth.
		2067	This scheme allows existing <filename>PR</filename> values
		2068	to be used for whatever reasons, which include manual
		2069	<filename>PR</filename> bumps should it be necessary.
		2070	</para>
		2071
		2072	<para>
		2073	By default, there is no server that runs the PR Service.
		2074	Thus, the packages generated are just "self consistent".
		2075	The build system adds and removes packages and
		2076	there are no guarantees about upgrade paths.
		2077	</para>
		2078
		2079	<para>
		2080	The simplest form for a PR Service is for it to exist
		2081	for a single host development system that builds the
		2082	package feed (building system).
		2083	For this scenario, you can enable the PR Service by adding
		2084	the following to your <filename>local.conf</filename>
		2085	file in the
		2086	<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
		2087	<literallayout class='monospaced'>
		2088	PRSERV_HOST = "localhost:0"
		2089	</literallayout>
		2090	Once the service is started, packages will automatically
		2091	get increasing <filename>PR</filename> values and
		2092	BitBake will take care of starting and stopping the server.
		2093	</para>
		2094
		2095	<para>
		2096	If you have a more complex setup where multiple host
		2097	development systems work against a common, shared package
		2098	feed, you have a single PR Service running and it is
		2099	connected to each building system.
		2100	For this scenario, you need to start the PR Service using
		2101	the <filename>bitbake-prserv</filename> command:
		2102	<literallayout class='monospaced'>
		2103	bitbake-prserve &dash;&dash;host <ip> &dash;&dash;port <port> &dash;&dash;start
		2104	</literallayout>
		2105	In addition to hand-starting the service, you need to
		2106	update the <filename>local.conf</filename> file of each
		2107	building system as described earlier so each system
		2108	points to the server and port.
		2109	</para>
		2110
		2111	<para>
		2112	It is also recommended you use build history, which adds
		2113	some sanity checks to package versions, in conjunction with
		2114	the server that is running the PR Service.
		2115	To enable build history, add the following to each building
		2116	system's <filename>local.conf</filename> file:
		2117	<literallayout class='monospaced'>
		2118	# It is recommended to activate "buildhistory" for testing the PR service
		2119	INHERIT += "buildhistory"
		2120	BUILDHISTORY_COMMIT = "1"
		2121	</literallayout>
		2122	For information on build history, see the
		2123	"<ulink url='&YOCTO_DOCS_REF_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
		2124	section in the Yocto Project Reference Manual.
		2125	</para>
		2126
		2127	<note>
		2128	The OpenEmbedded build system does not maintain
		2129	<filename>PR</filename> information as part of the
		2130	shared state (sstate) packages.
		2131	If you maintain an sstate feed, its expected that either
		2132	all your building systems that contribute to the sstate
		2133	feed use a shared PR Service, or you do not run a PR
		2134	Service on any of your building systems.
		2135	Having some systems use a PR Service while others do
		2136	not leads to obvious problems.
		2137	</note>
		2138	</section>
		2139
		2140	<section id='manually-bumping-pr'>
		2141	<title>Manually Bumping PR</title>
		2142
		2143	<para>
		2144	If a committed change results in changing the package output,
		2145	then the value of the PR variable needs to be increased
		2146	(or "bumped") as part of that commit.
		2147	For new recipes you should add the <filename>PR</filename>
		2148	variable and set its initial value equal to "r0", which is the default.
		2149	Even though the default value is "r0", the practice of adding it to a new recipe makes
		2150	it harder to forget to bump the variable when you make changes
		2151	to the recipe in future.
		2152	</para>
		2153
		2154	<para>
		2155	If you are sharing a common <filename>.inc</filename> file with multiple recipes,
		2156	you can also use the
		2157	<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-INC_PR'>INC_PR</ulink></filename>
		2158	variable to ensure that
		2159	the recipes sharing the <filename>.inc</filename> file are rebuilt when the
		2160	<filename>.inc</filename> file itself is changed.
		2161	The <filename>.inc</filename> file must set <filename>INC_PR</filename>
		2162	(initially to "r0"), and all recipes referring to it should set <filename>PR</filename>
		2163	to "$(INC_PR).0" initially, incrementing the last number when the recipe is changed.
		2164	If the <filename>.inc</filename> file is changed then its
		2165	<filename>INC_PR</filename> should be incremented.
		2166	</para>
		2167
		2168	<para>
		2169	When upgrading the version of a package, assuming the
		2170	<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'>PV</ulink></filename>
		2171	changes, the <filename>PR</filename> variable should be reset to "r0"
		2172	(or "$(INC_PR).0" if you are using <filename>INC_PR</filename>).
		2173	</para>
		2174
		2175	<para>
		2176	Usually, version increases occur only to packages.
		2177	However, if for some reason <filename>PV</filename> changes but does not
		2178	increase, you can increase the
		2179	<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PE'>PE</ulink></filename>
		2180	variable (Package Epoch).
		2181	The <filename>PE</filename> variable defaults to "0".
		2182	</para>
		2183
		2184	<para>
		2185	Version numbering strives to follow the
		2186	<ulink url='http://www.debian.org/doc/debian-policy/ch-controlfields.html'>
		2187	Debian Version Field Policy Guidelines</ulink>.
		2188	These guidelines define how versions are compared and what "increasing" a version means.
		2189	</para>
		2190
		2191	<para>
		2192	There are two reasons for following the previously mentioned guidelines.
		2193	First, to ensure that when a developer updates and rebuilds, they get all the changes to
		2194	the repository and do not have to remember to rebuild any sections.
		2195	Second, to ensure that target users are able to upgrade their
		2196	devices using package manager commands such as <filename>opkg upgrade</filename>
		2197	(or similar commands for dpkg/apt or rpm-based systems).
		2198	</para>
		2199
		2200	<para>
		2201	The goal is to ensure the Yocto Project has packages that can be upgraded in all cases.
		2202	</para>
		2203	</section>
2042	</section>	2204	</section>
2043		2205
2044	<section id="usingpoky-configuring-DISTRO_PN_ALIAS">	2206	<section id="usingpoky-configuring-DISTRO_PN_ALIAS">