Attachment 416754 Details for Bug 565560 – 0001-general-concepts-ebuild-revisions-rewrite-most-of-th.patch

[patch] 0001-general-concepts-ebuild-revisions-rewrite-most-of-th.patch

0001-general-concepts-ebuild-revisions-rewrite-most-of-th.patch (text/plain), 4.09 KB, created by Michael Orlitzky on 2015-11-12 03:56:21 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Michael Orlitzky

Created: 2015-11-12 03:56:21 UTC

Size: 4.09 KB

patch

obsolete

>From 56ed3c67dc46cf024ba97b08fd85c751703c5d62 Mon Sep 17 00:00:00 2001
>From: Michael Orlitzky <mjo@gentoo.org>
>Date: Mon, 14 Sep 2015 20:16:57 -0400
>Subject: [PATCH 1/1] general-concepts/ebuild-revisions: rewrite most of the
> text (bug #560356).
>
>As a prerequisite for bug #516612, our revision policy and
>documentation needs to be clarified. This is my attempt at a
>"fool-proof" rewrite of the Ebuild Revisions page.
>
>The biggest change is that a revision bump is suggested by default,
>and a (smaller) list of exceptions to that rule is provided.
>---
> general-concepts/ebuild-revisions/text.xml | 65 ++++++++++++++++++------------
> 1 file changed, 39 insertions(+), 26 deletions(-)
>
>diff --git a/general-concepts/ebuild-revisions/text.xml b/general-concepts/ebuild-revisions/text.xml
>index 012745f..f8d26a6 100644
>--- a/general-concepts/ebuild-revisions/text.xml
>+++ b/general-concepts/ebuild-revisions/text.xml
>@@ -5,41 +5,54 @@
> 
> <body>
> 
>-Ebuilds may have a Gentoo revision number associated with them. This is a
>-<c>-rX</c> suffix, where <c>X</c> is an integer <d/> see <uri
>-link="::ebuild-writing/file-format#File Naming Rules"/>. This
>-component must only be used for Gentoo changes, not upstream releases. By
>-default, <c>-r0</c> is implied.
>+ Ebuilds may have a revision suffix of the form <c>-rX</c>, where the
>+ Gentoo <e>revision number</e> <c>X</c> is a natural number <d/> see
>+ <uri link="::ebuild-writing/file-format#File Naming Rules"/>. The
>+ revision number indicates the <e>ebuild version</e> and is
>+ independent of the upstream package version. A default revision
>+ number of <c>0</c> is implied. New revisions of existing ebuilds
>+ are often called &quot;revision bumps,&quot; or &quot;revbumps&quot;
>+ for short.
> 
> 
> 
>-Ebuilds should have their <c>-rX</c> incremented whenever a change is made which
>-will make a substantial difference to what gets installed by the package <d/> by
>-substantial, we generally mean "something for which many users would want to
>-upgrade". This is usually for bugfixes.
>-For any such revision bump, the new ebuild should be based on the
>-previous revision to ensure that fixes aren't dropped accidentally.
>+ Increment the revision number whenever you change an ebuild. New
>+ revisions are subject to the <uri link="::keywording#Keywording on
>+ Upgrades">keyword policy for upgrades</uri>, and should be based on
>+ the <e>previous</e> revision so that fixes are not accidentally
>+ dropped. A few exceptions to this rule are outlined below. If you
>+ are unsure, increment the revision number.
> 
> 
>-
>-Simple compile fixes do not warrant a revision bump; this is because they do
>-not affect the installed package for users who already managed to compile it.
>-Small documentation fixes are also usually not grounds for a new revision.
>-In particular, this applies if the package has a substantial compilation
>-time; developers should use their best judgement in these circumstances.
>-
>-
>-<important>
>-For ebuilds marked stable on at least one arch, only trivial edits can be made
>-without a bump (e.g. typo fixes in elog messages). Even simple changes may
>-result in a breakage. Modifying stable ebuilds should be avoided.
>-</important>
>+<warning>
>+ These exceptions do not apply to stable ebuilds. Only under
>+ exceptional circumstances should you modify an
>+ ebuild that is marked stable on any arch.
>+</warning>
> 
> 
>-When doing a revision bump, the usual rules about dropping to <c>~arch</c> apply.
>-See <uri link="::keywording#Keywording on Upgrades"/>.
>+ In the following cases, you may modify an ebuild in-place:
> 
> 
>+<ul>
>+ <li>
>+ Fixes for compilation failures. These do not affect users
>+ who have already managed to build the package, so there's no
>+ reason to force the package to be rebuilt.
>+ </li>
>+ <li>
>+ Changes to comments.
>+ </li>
>+ <li>
>+ Trivial fixes (for example, typos) in elog messages.
>+ </li>
>+ <li>
>+ Modification of build-time dependencies. Use this exception
>+ sparingly and only if the package takes an extremely long time to
>+ compile.
>+ </li>
>+</ul>
>+
> </body>
> </chapter>
> </guide>
>-- 
>2.4.10
>

Actions: View | Diff

Attachments on bug 565560: 416754 | 440976