[gentoo-dev] Proper KEYWORDing

[Ciaran McCreesh]

Well, it looks like I need to resend this...

=== New Packages

When adding new packages to the tree, only include KEYWORDS for archs on
which you have actually tested. Note that "tested" does not equate to
"compiled it with one particular combination of USE flags and didn't see
any errors". Also, "you" does not mean "some random bloke on IRC who
isn't a developer".

If it's a user-submitted ebuild, don't assume that the submitter has
done testing on lots of archs if they include lots of keywords --
chances are they just copied the KEYWORDS line in from another package.

New packages shouldn't be keyworded stable on any arch directly. Always
commit as ~arch and then stable later.

Don't assume that upstream's list of "supported archs" correlates with
Gentoo.  We might not be using the same toolchain as them. They might be
lying. They might just have tested one particular version twenty
releases ago.

The same applies for Debian's list of archs. That's only a compile test,
and again they don't use the same toolchain. Oh, and they might have
patches.

If you're pretty sure that a package is arch-neutral, feel free to Cc:
other archs on the bug after you've added the ebuild to the tree and ask
them to consider keywording. Definitely do this if your package is cool;
don't bother if it's some lame WindowMaker dockapp or if it has 'emacs'
in the name.

Just because it's a perl script does not mean it's arch-neutral.

=== Adding in New Keywords

Do not add in an ~arch keyword to an existing package unless you have
tested on that arch. See earlier note for what "tested" means.

Keywording bugs should be handled by the arch team in question who will
do proper testing before adding in the keyword. We've had a fair number
of keyword bugs where the user has only compile-tested the app and not
tried to run it, or hasn't checked certain USE flag combinations.

=== Moving an Ebuild from ~arch to arch

DO NOT EVER MARK A PACKAGE STABLE on any arch on which you haven't
tested. If you want to get an ebuild moved to stable, file a bug for the
relevant archs or prod them repeatedly on IRC until they get sick of you
and go and keyword the thing just to shut you up. Note that the second
option doesn't work for people who know how to use /ignore or /kick.

Arch teams: when moving from ~arch to arch on an actively maintained
package where you're going ahead of the maintainer's arch, it's best to
consult first.  You don't necessarily have to follow the maintainer's
advice, but at least listen to what they have to say.

=== Version Bumps

When doing a version bump, all existing arch keywords should be dropped
to ~arch. Existing ~arch keywords should be left in.

If a package is a really big change, it may be wise to drop keywords
entirely for untested archs. You must file a bug if you do this.

[ Exception: A few packages which have arch-specific patchsets and / or
are very arch-sensitive (for example, some kernel sources) are handled
differently. If you work with one of these packages, you should know how
this works... ]

If a new version introduces new dependencies which are not available on
some archs, file a bug for the archs or ask on IRC before you do the
bump. If you really need to get the ebuild added to the tree in a hurry,
drop the keywords which are causing problems, but don't forget to file a
bug letting the archs in question know what you've done.

Do not remove keywords just to shut repoman up. If repoman is
complaining about an arch which you didn't break yourself, first try a
full cvs update. If it's still broken, file a bug for the broken arch.

=== Sidenote on Dependencies

Some optional dependencies pretty much have to be arch specific. Things
which are binary-only or rely upon certain kernel features are the most
common here.  Although you *could* do DEPEND="!somearch? ( blah? (
libblah ) )", it's better to ask the arch in question to use.mask the
blah flag.  That way the USE flag will show up as being forced off on a
given arch, rather than being selectable but not doing anything.

=== Eclasses

When making dependency changes in an eclass, don't forget to manually
check that you're not breaking any archs. Repoman is no good here. It
won't cry if, say, you update the eclass' DEPEND upon fooapp-config from
>=1.5 to >=1.7 without checking that 1.7 is stable on all archs first.

=== Removing Packages

When tidying up, never remove the newest stable package for any arch. If
you'd like to get a newer version marked stable on some archs, file a
bug or ask on IRC. Be very very careful! Even Aron screwed this up once
:)

When tidying up ~arch, make sure you don't force a downgrade for any
arch (unless of course you're deliberately doing so because of a nasty
bug).

=== Friendly Reminder

Every time you screw up, you cause a lot of work for the arch teams.
Spending an extra minute when making your change to get it right can
save several hours of work from each of the arch teams. The arch teams
are not there to clean up your mess. Do you really want to wake up and
find http://dev.gentoo.org/~todd/blah.jpg staring you in the face?

=== Summary

* Don't keyword on archs on which you can't test

* Don't drop keywords without letting arch teams know

* Don't break dependencies

* Be careful when tidying up

-- 
Ciaran McCreesh : Gentoo Developer (Sparc, MIPS, Vim, Fluxbox)
Mail            : ciaranm at gentoo.org
Web             : http://dev.gentoo.org/~ciaranm