Gentoo Archives: gentoo-dev

From: Ciaran McCreesh <ciaranm@g.o>
To: gentoo-dev@l.g.o
Subject: [gentoo-dev] Proper KEYWORDing
Date: Fri, 30 Jul 2004 18:22:45
Message-Id: 20040730191959.246f461b@snowdrop.home
1 In an ideal world, this email would be totally unnecessary, and I would
2 have spent the past hour or so fixing up vim to make it auto detect
3 whether you're running on a light or dark terminal. However, it seems
4 that certain mentors aren't doing a very good job of teaching their
5 recruits, and certain devs are going around screwing up the tree, and
6 unfortunately Weeve isn't around to post his monthly "stop breaking my
7 stuff" email... So...
9 === Hastily Written Guide to Not Getting Lynched by the Arch Devs ===
11 === New Packages
13 When adding new packages to the tree, only include KEYWORDS for archs on
14 which you have actually tested. Note that "tested" does not equate to
15 "compiled it with one particular combination of USE flags and didn't see
16 any errors". Also, "you" does not mean "some random bloke on IRC who
17 isn't a developer".
19 If it's a user-submitted ebuild, don't assume that the submitter has
20 done testing on lots of archs if they include lots of keywords --
21 chances are they just copied the KEYWORDS line in from another package.
23 New packages shouldn't be keyworded stable on any arch directly. Always
24 commit as ~arch and then stable later.
26 Don't assume that upstream's list of "supported archs" correlates with
27 Gentoo. We might not be using the same toolchain as them. They might be
28 lying. They might just have tested one particular version twenty
29 releases ago.
31 The same applies for Debian's list of archs. That's only a compile test,
32 and again they don't use the same toolchain. Oh, and they might have
33 patches.
35 If you're pretty sure that a package is arch-neutral, feel free to Cc:
36 other archs on the bug after you've added the ebuild to the tree and ask
37 them to consider keywording. Definitely do this if your package is cool;
38 don't bother if it's some lame WindowMaker dockapp or if it has 'emacs'
39 in the name.
41 Just because it's a perl script does not mean it's arch-neutral.
43 === Adding in New Keywords
45 Do not add in an ~arch keyword to an existing package unless you have
46 tested on that arch. See earlier note for what "tested" means.
48 Keywording bugs should be handled by the arch team in question who will
49 do proper testing before adding in the keyword. We've had a fair number
50 of keyword bugs where the user has only compile-tested the app and not
51 tried to run it, or hasn't checked certain USE flag combinations.
53 === Moving an Ebuild from ~arch to arch
55 DO NOT EVER MARK A PACKAGE STABLE on any arch on which you haven't
56 tested. If you want to get an ebuild moved to stable, file a bug for the
57 relevant archs or prod them repeatedly on IRC until they get sick of you
58 and go and keyword the thing just to shut you up. Note that the second
59 option doesn't work for people who know how to use /ignore or /kick.
61 Arch teams: when moving from ~arch to arch on an actively maintained
62 package where you're going ahead of the maintainer's arch, it's best to
63 consult first. You don't necessarily have to follow the maintainer's
64 advice, but at least listen to what they have to say.
66 === Version Bumps
68 When doing a version bump, all existing arch keywords should be dropped
69 to ~arch. Existing ~arch keywords should be left in.
71 If a package is a really big change, it may be wise to drop keywords
72 entirely for untested archs. You must file a bug if you do this.
74 [ Exception: A few packages which have arch-specific patchsets and / or
75 are very arch-sensitive (for example, some kernel sources) are handled
76 differently. If you work with one of these packages, you should know how
77 this works... ]
79 If a new version introduces new dependencies which are not available on
80 some archs, file a bug for the archs or ask on IRC before you do the
81 bump. If you really need to get the ebuild added to the tree in a hurry,
82 drop the keywords which are causing problems, but don't forget to file a
83 bug letting the archs in question know what you've done.
85 Do not remove keywords just to shut repoman up. If repoman is
86 complaining about an arch which you didn't break yourself, first try a
87 full cvs update. If it's still broken, file a bug for the broken arch.
89 === Sidenote on Dependencies
91 Some optional dependencies pretty much have to be arch specific. Things
92 which are binary-only or rely upon certain kernel features are the most
93 common here. Although you *could* do DEPEND="!somearch? ( blah? (
94 libblah ) )", it's better to ask the arch in question to use.mask the
95 blah flag. That way the USE flag will show up as being forced off on a
96 given arch, rather than being selectable but not doing anything.
98 === Eclasses
100 When making dependency changes in an eclass, don't forget to manually
101 check that you're not breaking any archs. Repoman is no good here. It
102 won't cry if, say, you update the eclass' DEPEND upon fooapp-config from
103 >=1.5 to >=1.7 without checking that 1.7 is stable on all archs first.
105 === Removing Packages
107 When tidying up, never remove the newest stable package for any arch. If
108 you'd like to get a newer version marked stable on some archs, file a
109 bug or ask on IRC. Be very very careful! Even Aron screwed this up once
110 :)
112 When tidying up ~arch, make sure you don't force a downgrade for any
113 arch (unless of course you're deliberately doing so because of a nasty
114 bug).
116 === Friendly Reminder
118 Every time you screw up, you cause a lot of work for the arch teams.
119 Spending an extra minute when making your change to get it right can
120 save several hours of work from each of the arch teams. The arch teams
121 are not there to clean up your mess. Do you really want to wake up and
122 find staring you in the face?
124 === Summary
126 * Don't keyword on archs on which you can't test
128 * Don't drop keywords without letting arch teams know
130 * Don't break dependencies
132 * Be careful when tidying up
134 --
135 Ciaran McCreesh : Gentoo Developer (Sparc, MIPS, Vim, Fluxbox)
136 Mail : ciaranm at
137 Web :