[gentoo-dev] RFC: Dev-only Wiki for eclasses/portage

[Bjoern Michaelsen]

Hi gentoo-Devs!

Im writing a few ebuilds and am trying to do it right - using
eclass funtions and stuff. Since this is java stuff not using
make it is not the standard "./configure;make;make install".
This is when the following idea creeped into my mind:

This a RFC: 
What do you think about a public wiki, writeable by devs, where
eclasses can be documented in a quick-and-dirty way?
Additionally information on best practices can be made available
in the wiki too.

Motivation:
To better the quality on user-commited ebuilds.

Rationale:
Any doc is better than no doc.
Nicely formatted and formulated gentoo-docs are a very good
thing. But for the few users building ebuilds it is not that
important to have good looking Guide-XML docs, but it is
important to have something more than the raw eclasses-sources.
I assume there are huge amounts of functionality in the
eclasses, but it is really hard to find a starting point for a
user and for devs-to-be.  I
I have seen the conplains about the quality of user-commited
ebuilds on this list and think one of the reasons is the lack of
docs for eclasses. In addition to the hope that users get their
ebuild better the first time, devs can reject ebuilds with a
link to the guidelines that where not followed. This helps in
three ways: The user might fix it himself and he is less
frustrated, because he knows the reasons for the rejection and
the devs dont have to get verbose over the same issues again and
again. A sideeffect might be that a best practices standard
might evolve that betters the overall code quality of ebuilds
in portage.

Backwards Compability:
No problems here.


Now you can start flaming me.

Yours, Björn
-- 
Björn Michaelsen
pub  1024D/C9E5A256 2003-01-21 Björn Michaelsen <bmichaelsen@×××.de>
   Key fingerprint = D649 8C78 1CB1 23CF 5CCF  CA1A C1B5 BBEC C9E5 A256