[Documentation/CODE] - added more overlay policies

1 files changed, 91 insertions, 7 deletions

diff --git a/Documentation/CODE b/Documentation/CODE
index ce7e3a671fc..b602a93d769 100644
--- a/Documentation/CODE
+++ b/Documentation/CODE
@@ -1,12 +1,18 @@
 WHAT RULES I SHOULD FOLLOW WHEN I WANT WORK ON SOMETHING FOR KDE TEAM?
 If you asked this question you are reading right file.
 
-So the rules are these:
+KDE4 (kde-testing) policies:
+
+ - append Changelog and valid metadata.xml - not necessarily with <herd>kde</herd> if you're proxy
+   maintaining some ebuild.
+
+ - always separate DEPEND and RDEPEND properly (adding COMMON_DEPEND if needed)
 
  - always use kde4-* eclasses. kde4-base for applications with main CMakeLists.txt in toplevel
    source directory, kde4-meta for applications hidden deeper in source code directory structure
    and requiring common CMakeLists.txt from toplevel directory.
    See also KMEXTRA, KMEXTRACTONLY, KMCOMPILEONLY eclass variables.
+   NEVER FORGET TO INVOKE kde4-{base,meta}_${phase_function} when overriding ebuild phase!
 
  - always report CMake issues about everything directly to upstream and backport their fix.
 
@@ -19,6 +25,10 @@ So the rules are these:
  - think about adding debug USE flag to your package. Do not add debug USE flag for artwork-only and
    python-only KDE packages. And don't forget to write metadata.xml entries for new local USE flags.
 
+ - do not enable USE flags by default (IUSE="+useflag") with no *good* reason. "Because I use it" it's
+   not enough. If uncertain - discuss it with the rest of the team. USE flags that are considered as
+   commonly used, known to work and not pulling any dependencies, can be enabled by default right away.
+
  - always check for linguas and add them to the KDE_LINGUAS variable.
 
  - always fix automagic packages with macro_optional_ prefixing and report it upstream with patch.
@@ -32,8 +42,8 @@ So the rules are these:
    Block, if possible should contain specific version for the blocker. Below are most typical
    scenarios for kde-base/ related blocks, your should use this as a pattern, unless you know what you're doing.
 
-- all kde4 and kde-live misc applications should be in SLOT="4". Feel free to fix packages that don't
-  follow this, and always add the correct blockers (be carefull not to block kde3 packages)
+ - all kde4 and kde-live misc applications should be in SLOT="4". Feel free to fix packages that don't
+   follow this, and always add the correct blockers (be carefull not to block kde3 packages)
 
    * ebuild rename not colliding with KDE3 ebuilds (see example kde-menu -> kdebase-menu)
 
@@ -50,6 +60,8 @@ TODO
 
 Commiting:
 
+ - always run repoman full on ebuild subtree you're working on before commiting *anything*
+
  - try to keep one commit per change if possible. If more appropriate - one commit per feature.
 
  - all commit messages must look like this:
@@ -78,11 +90,83 @@ Examples:
    Remember to do not edit autogenerated files, as your changes will be lost in next
    regenerate-files tool run.
 
-KDE 3:
+QA:
+
+   - keep ebuilds clean, look at recommended ebuild formatting rules below (obligatory for kde-base).
+     Use existing ebuilds (like kdelibs) for reference.
+
+   * sort dependencies alphabetically - it makes it easier to manage them later
+
+	>=app-misc/strigi-0.6.3[dbus,qt4]
+	dev-libs/libpcre
+	dev-libs/libxml2
+
+   * try to separate KEYWORDS and IUSE with some usually invariant variable (like SLOT) - it makes
+     it easier to merge changes between live and tagged ebuilds using GUI diff/merge tools.
+     Always *avoid* merging/synchronizing ebuilds manually if possible - it's error prone.
+     Use kompare <srcfile> <destfile> for it.
+
+KEYWORDS="~amd64 ~x86"
+LICENSE="LGPL-2.1"
+IUSE="3dnow acl alsa altivec bindist +bzip2 debug doc fam jpeg2k kerberos
+mmx nls openexr +semantic-desktop spell sse sse2 ssl zeroconf"
+
+   * put blocks at the begin of RDEPEND section, !useflag? ( ) preferably before useflag? ( ) -
+     - it's easier to spot them when they're in expected location
+
+RDEPEND="${DEPEND}
+	!kdeprefix? ( !kde-base/phonon-xine[-kdeprefix] )
+"
+
+   * put optional dependencies after obligatory ones - again - improves readability
+
+	x11-proto/renderproto
+	xinerama? ( x11-proto/xineramaproto )
+
+   * avoid single line expressions - they are utterly unreadable
+
+	ssl? ( dev-libs/openssl )
+	zeroconf? (
+		|| (
+			net-dns/avahi[mdnsresponder-compat]
+			!bindist? ( net-misc/mDNSResponder )
+		)
+	)
+
+   * always indent dependencies with <tab> characters from new line (including other variable like
+     ${COMMONDEPEND} may be exception here) and always break line *after* dependency - it makes it easier to
+     synchronize such deps semi-automatically between ebuilds using GUI diff/merge tools (less conflicts).
+     The same applies to PATCHES as well.
+
+COMMONDEPEND="
+	>=app-misc/strigi-0.6.3[dbus,qt4]
+"
+# sth? ( dev/foo ) - re-add when in tree
+DEPEND="${COMMONDEPEND}
+	doc? ( app-doc/doxygen )
+	nls? ( virtual/libintl )
+"
+
+PATCHES=(
+	"${FILESDIR}/dist/09_disable_debug_messages_if_not_explicitly_enabled.patch"
+	"${FILESDIR}/dist/20_use_dejavu_as_default_font.patch"
+	"${FILESDIR}/dist/23_solid_no_double_build.patch"
+)
+
+
+
+
+
+KDE 3 rules
+
+ - use kde-crazy overlay for your KDE3 experimental/testing work
+
  - do what ever you want with one condition, make sure it really compiles/run
+
  - feel free to commit patches without kde team ack if the above condition is checked
- - all kde3 apps should have SLOT="3.5". Feel free to fix packages that don't follow this
-   rule and don't forget to add correct blockers
 
-# NOT FOLLOWING THIS RULES WILL BE PUNISHED!
+ - all kde3 apps should have SLOT="3.5". Feel free to fix packages that don't follow this rule and don't
+   forget to add correct blockers
+
+# NOT FOLLOWING THESE RULES WILL BE PUNISHED!
 # no cookies for week!