Bug 223153 – Devmanual documentation for ebuild revbumping is incomplete

• Product: Documentation
• Status: RESOLVED FIXED

[Description Nirbheek Chauhan (RETIRED) 2008-05-22 02:40:00 UTC]

The devmanual only lists two polar cases as examples for when to revbump an ebuild, and when not to; namely:

- revbump for bugfixes
- don't for compile fixes

This leaves a wide area of doubt where the developer is unsure whether to revbump or not. This might also lead to inconsistency in revbumping.

For example: (#gentoo-dev)
<darksiide> i need advice, a package that is marked stable is missing a dep in RDEPEND, I'm going to add it...what should i do, rev bump? just add it? (the package has always been like this, btw)
* bheekling would guess revbump since it's not a change that affects only the build process
* ABCD (n=ABCD@wikipedia/ABCD) has joined #gentoo-dev
* bheekling is not sure however and wonders if there's any documentation about this
<darksiide> heh
<nerdboy> alternatively, those with the missing dep wouldn't be affected...
<darksiide> i agree
<bheekling> darksiide, what kind of an RDEPEND is this?
<bheekling> ie, is it an optional rdepend?
<bheekling> (in which case users might not notice that it's not there)
<darksiide> netkit-talk needs virtual/xinetd..or else it cannot be started
<bheekling> Ah, now I say just add the depend :P

Other examples are for changes in the ebuild structure; some of the changes might warrant a revbump, some might not.

Of course, it's not possible to list every single situation; I leave it to the doc team to figure out the solution ;)

[Comment 1 Aleksandar Petrinic 2011-06-23 01:16:20 UTC]

Dev manual is so vague that I'm not able to fill QA bugs properly, especially about revision bumps policies.

It states "Ebuilds should have their -rX incremented whenever a change is made which will make a substantial difference to what gets installed by the package"

So, in theory, every gained dependency should be bumped.

but then the manual tries to clarify:"by substantial, we generally mean "something for which many users would want to upgrade"."

Totally confusing!! I suppose I have to make a survey everytime I hit a missed revision bump to fill the bug...

Be serious, this is NOT QA at all!! We will never get bullet-proof updates if we have crappy rules.

Recently portage and paludis added an option to handle this kind of QA violation.

--rebuild-if-new-rev for portage.
--keep/--keep-targets if-same-metadata for paludis.

I was really surprised of how many packages in the tree do something weird with their dependencies keeping the very same version and revision. Last time I checked I found ~270 packages that "probably"(I hope not all of them) violate the policy.

The point is stop to hide the dust under the carpet! Now thanks to PMs support, the pandora's box has already been opened, so like for every serious QA process we need policies we can rely on to determinate if something is legal or not!!

Please fix the devmanual so I can start to check(one by one) the indicted packages and fill (eventually) the bugs about them.... I really don't want to follow the current devmanual and start making survey to fill bugs.

Thanks.

[Comment 2 Michael Orlitzky 2019-04-25 11:39:36 UTC]

I still strongly disagree with two of the items,

  2. If the change makes a substantial difference to the user who already 
     installed the package (fixes runtime issues, changes installed files, etc.) 
     and it would not be propagated using other means, then the ebuild should be 
     renamed to a new revision. If the package has stable keywords, they should 
     be moved to the new revision without dropping. To commit the ebuild, repoman 
     commit --straight-to-stable option should be used. 

     (contradicts stabilization policy and all other documentation)

  ... 
 
  * adding a new USE flag or removing an existing one (since change in USE flags 
    is going to trigger --changed-use rebuild), 

    (requires a portage-only feature to avoid breakage)

but in any case, the page at

  https://devmanual.gentoo.org/general-concepts/ebuild-revisions/index.html

is now pretty clear. Should we close this?

[Comment 3 Michael Orlitzky 2019-11-21 23:29:58 UTC]

Why is it so hard to get even a yes/no answer out of devmanual@ on bugzilla?