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... |
8 |
|
9 |
=== Hastily Written Guide to Not Getting Lynched by the Arch Devs === |
10 |
|
11 |
=== New Packages |
12 |
|
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". |
18 |
|
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. |
22 |
|
23 |
New packages shouldn't be keyworded stable on any arch directly. Always |
24 |
commit as ~arch and then stable later. |
25 |
|
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. |
30 |
|
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. |
34 |
|
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. |
40 |
|
41 |
Just because it's a perl script does not mean it's arch-neutral. |
42 |
|
43 |
=== Adding in New Keywords |
44 |
|
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. |
47 |
|
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. |
52 |
|
53 |
=== Moving an Ebuild from ~arch to arch |
54 |
|
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. |
60 |
|
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. |
65 |
|
66 |
=== Version Bumps |
67 |
|
68 |
When doing a version bump, all existing arch keywords should be dropped |
69 |
to ~arch. Existing ~arch keywords should be left in. |
70 |
|
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. |
73 |
|
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... ] |
78 |
|
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. |
84 |
|
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. |
88 |
|
89 |
=== Sidenote on Dependencies |
90 |
|
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. |
97 |
|
98 |
=== Eclasses |
99 |
|
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. |
104 |
|
105 |
=== Removing Packages |
106 |
|
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 |
:) |
111 |
|
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). |
115 |
|
116 |
=== Friendly Reminder |
117 |
|
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 http://dev.gentoo.org/~todd/blah.jpg staring you in the face? |
123 |
|
124 |
=== Summary |
125 |
|
126 |
* Don't keyword on archs on which you can't test |
127 |
|
128 |
* Don't drop keywords without letting arch teams know |
129 |
|
130 |
* Don't break dependencies |
131 |
|
132 |
* Be careful when tidying up |
133 |
|
134 |
-- |
135 |
Ciaran McCreesh : Gentoo Developer (Sparc, MIPS, Vim, Fluxbox) |
136 |
Mail : ciaranm at gentoo.org |
137 |
Web : http://dev.gentoo.org/~ciaranm |