[gentoo-dev] Revisions for USE flag changes

[Michael Orlitzky <mjo@gentoo.org>]

We have a pull request for the devmanual that will update the revision
documentation; namely, when to create a new one:

  https://github.com/gentoo/devmanual.gentoo.org/pull/67

The comments bring up an issue that I think can benefit from some
hindsight. Specifically, the PR says that it's OK to change IUSE without
creating a revision, because users can use --changed-use to catch it.
My immediate objection to that was that --changed-use is specific to
Portage, but let's reflect on the status quo.


== The situation now ==

  1 We tell everyone to update with either --newuse or --changed-use.

  2 Developers change IUSE without new revisions.

  3 To facilitate (1) and (2), Portage has the --changed-use and
    --newuse flags. Paludis has a family of "--keep" options to avoid
    reinstallation, e.g. --keep=if-same-metadata. And pkgcore has its
    own (different) --newuse flag.

  4 There is no specification for the features in (3), and each package
    manager has taken a different approach.


The end result is that Portage users do see the changes made to IUSE
without a revision, but at a cost:

  * They have to pass the "required" --changed-use or --newuse flags to
    every command.

  * The same cannot be said for users of other package managers.

  * Lots of PM code exists to handle this stuff.

  * Our documentation needs to describe the above (relatively)
    complicated situation.


And with one notable benefit:

  * We don't need to rename the ebuild to change IUSE, and in theory we
    can control when rebuilds happen.



== New revisions for USE flag changes ==

I suggest that in hindsight, we can do better. Suppose we require a new
revision for every change to IUSE. Then,

  * We can delete all of the PM code for --changed-use and --newuse and
    friends.

  * The documentation becomes much simpler: revbump if IUSE changes.

  * Users can omit --newuse and --changed-use from their lives.

  * All package managers now handle IUSE changes properly.

  * emerge runs a bit faster.

This has none of the downsides of the current approach. Of course, it
lacks that one benefit -- that you don't have to rename the ebuild when
you change IUSE. Now I'll try to convince you that the rename and
associated rebuilds aren't that big of a deal.


Q. But what about the rebuilds?

  For most packages, the rebuilds simply don't matter. Unless you're
  the maintainer of libreoffice, firefox, chromium, etc. -- just do the
  revision and forget about the (quick) rebuilds.

  We tell everyone to use --changed-use and --newuse if they want
  things to work, so they were probably going to rebuild anyway.


Q. But what if I maintain firefox, and I need to change  IUSE?

  If the IUSE change isn't important, just make the new revision in a
  branch and wait to commit it later when there are more changes
  piled up. If it is important (like if its default value changes
  RDEPEND), then it would have required a revision anyway.


Q. But I work on a team, and we can't all work in different branches.

  If you work on a massive package and if you're collaborating with
  others regularly, you can commit the new ebuild masked. This is
  annoying, but is an extremely rare combination of circumstances.


== tl;dr ==

We would be better off with respect to IUSE changes and revisions if we
deleted the --changed-use and --newuse flags right now, and just
required developers to revbump when changing IUSE.

Package managers get simpler, documentation gets simpler, the user
interface gets simpler, and behavior becomes more uniform and predictable.

Please let me know what you think.