More detailed CODE guide - (TODO - blocks)

1 files changed, 68 insertions, 18 deletions

diff --git a/Documentation/CODE b/Documentation/CODE
index 5791b3efae6..49784ad5f65 100644
--- a/Documentation/CODE
+++ b/Documentation/CODE
@@ -2,28 +2,78 @@ 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:
- - always use kde4-* eclasses
- - always report cmake issues about everything directly to upstream and backport their fix
+
+ - 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.
+
+ - always report CMake issues about everything directly to upstream and backport their fix.
+
  - never use -j1 in ebuilds. Always report the issue upstream and wait for the resolution or fix yourself
- - doubleckeck the doc useflag in your package
- - think about adding debug useflag to your package
- - always check for linguas and add them to the KDE_LINGUAS variable
+
+ - doubleckeck the doc useflag in your package. For kde4-meta style ebuilds - look for doc/${PN}
+   or similar directory. Sometimes application handbooks are not trivial to assign (for example
+   kde-base/khelpcenter ebuild), in such case ask Gentoo KDE team/HT members or contact upstream.
+
+ - think about adding debug useflag to your package. Do not add debug USE flag for artwork-only and
+   python-only KDE packages.
+
+ - 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.
- - check your apps deps with dylink scanner in maintainer folder
- - if you want our herd in the application and you are not kde team HT/Member ask us first
- - if you create blocker make sure it is in RDEPEND and comment the reason why you created the blocker
-   the blocker must contain specific version for the block
-     ie. we introduce blocker for 4.1.87 then we add to the block !<cat/pn-4.1.87
-   remember to use correct +-kdeprefix resolution
-     !kdeprefix? ( !<cat/pn-version[kdeprefix-] )
-	 kdeprefix? ( !<cat/pn-version:slot[kdeprefix] )
+
+ - check your apps deps with dylink scanner in maintainer folder. Be aware, that this tool does not
+   return complete runtime dependency chain, still it will find most automagic linking dependencies.
+
+ - if you want our herd in the application and you are not Gentoo KDE team/HT member - ask us first.
+
+ - handle blocks carefully. Put blocks only in RDEPEND section and comment the reason for the block.
+   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.
+
+   * ebuild rename not colliding with KDE3 ebuilds (see example kde-menu -> kdebase-menu)
+
+   !kdeprefix? ( !<old_cat>/<old_pkg>[-kdeprefix] )
+   kdeprefix? ( !<old_cat>/<old_pkg>:${SLOT} )
+
+TODO
+TODO    ie. we introduce blocker for 4.1.87 then we add to the block !<cat/pn-4.1.87
+TODO    remember to use correct +-kdeprefix resolution
+TODO   !kdeprefix? ( !<cat/pn-version[kdeprefix-] )
+TODO   kdeprefix? ( !<cat/pn-version:slot[kdeprefix] )
+TODO
+
 
 Commiting:
- - All commit messages must look like this:
-   category/pn - Message describing what i did
-   kde-base/kdelibs - sync with main tree.
- - When you commit something for some bug add inOverlay to keywords, so normal devs know about it
-   also add [overlay-name] to the summary
+
+ - try to keep one commit per change if possible. If more appropriate - one commit per feature.
+
+ - all commit messages must look like this:
+
+   <category/pn> - <detailed message describing what you did>
+   Also append package version, when needed.
+
+Examples:
+
+   kde-base/kdelibs-4.2.3 - Synced with tree: fixed bug #333452, removed unnecessary solid patch, added debug to IUSE.
+
+   kde-base/kdelibs-4.2.3 - Moved to tree.
+
+ - when you commit something related to existing bugzilla bug, add inOverlay to keywords to that bug,
+   so that developers know about it. Also add [overlay-name] to bug summary.
+
+ - if you refactor ebuild names in kde-base, *always* synchronize those changes in following locations
+   if applicable:
+
+   * sets/
+
+   * Documantation/package.keywords/
+
+   * Documantation/package.unmask/
+
+   Remember to do not edit autogenerated files, as your changes will be lost in next
+   regenerate-files tool run.
 
 KDE 3:
  - do what ever you want with one condition, make sure it really compiles/run