From 86d45adf12ac65c87bc2b638a8575cb5dd94a08a Mon Sep 17 00:00:00 2001 From: Michael Orlitzky 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 | 62 ++++++++++++++++-------------- 1 file changed, 34 insertions(+), 28 deletions(-) diff --git a/general-concepts/ebuild-revisions/text.xml b/general-concepts/ebuild-revisions/text.xml index 012745f..8336226 100644 --- a/general-concepts/ebuild-revisions/text.xml +++ b/general-concepts/ebuild-revisions/text.xml @@ -5,40 +5,46 @@

-Ebuilds may have a Gentoo revision number associated with them. This is a --rX suffix, where X is an integer see . This -component must only be used for Gentoo changes, not upstream releases. By -default, -r0 is implied. + All ebuilds have a revision number. A revision number is an + -rX suffix, where X is a positive integer see + . The + revision number indicates the ebuild version and is + independent of the upstream package version. A default revision + number of r0 is implied. New revisions of existing ebuilds + are often called "revision bumps," or "revbumps" + for short.

-Ebuilds should have their -rX incremented whenever a change is made which -will make a substantial difference to what gets installed by the package 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 keyword policy for upgrades. A few exceptions to + this rule are outlined below. If you are unsure, increment the + revision number. However, in the following cases, you may modify an + ebuild in-place:

-

-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. -

- - -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. - + + These exceptions do not apply to stable ebuilds. Only under + exceptional circumstances should you modify a + stable ebuild. + -

-When doing a revision bump, the usual rules about dropping to ~arch apply. -See . -

+ -- 2.4.6