Gentoo Archives: gentoo-dev

From: Bjoern Michaelsen <bjoern.michaelsen@×××××.net>
To: gentoo-dev@l.g.o
Subject: [gentoo-dev] RFC: Dev-only Wiki for eclasses/portage
Date: Thu, 27 May 2004 23:25:45
Message-Id: 20040527232544.GA12162@lord.sinclair
1 Hi gentoo-Devs!
3 Im writing a few ebuilds and am trying to do it right - using
4 eclass funtions and stuff. Since this is java stuff not using
5 make it is not the standard "./configure;make;make install".
6 This is when the following idea creeped into my mind:
8 This a RFC:
9 What do you think about a public wiki, writeable by devs, where
10 eclasses can be documented in a quick-and-dirty way?
11 Additionally information on best practices can be made available
12 in the wiki too.
14 Motivation:
15 To better the quality on user-commited ebuilds.
17 Rationale:
18 Any doc is better than no doc.
19 Nicely formatted and formulated gentoo-docs are a very good
20 thing. But for the few users building ebuilds it is not that
21 important to have good looking Guide-XML docs, but it is
22 important to have something more than the raw eclasses-sources.
23 I assume there are huge amounts of functionality in the
24 eclasses, but it is really hard to find a starting point for a
25 user and for devs-to-be. I
26 I have seen the conplains about the quality of user-commited
27 ebuilds on this list and think one of the reasons is the lack of
28 docs for eclasses. In addition to the hope that users get their
29 ebuild better the first time, devs can reject ebuilds with a
30 link to the guidelines that where not followed. This helps in
31 three ways: The user might fix it himself and he is less
32 frustrated, because he knows the reasons for the rejection and
33 the devs dont have to get verbose over the same issues again and
34 again. A sideeffect might be that a best practices standard
35 might evolve that betters the overall code quality of ebuilds
36 in portage.
38 Backwards Compability:
39 No problems here.
42 Now you can start flaming me.
44 Yours, Björn
45 --
46 Björn Michaelsen
47 pub 1024D/C9E5A256 2003-01-21 Björn Michaelsen <bmichaelsen@×××.de>
48 Key fingerprint = D649 8C78 1CB1 23CF 5CCF CA1A C1B5 BBEC C9E5 A256