[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-commits
Subject:    koffice/libs
From:       Thomas Zander <zander () kde ! org>
Date:       2010-03-11 9:16:29
Message-ID: 1268298989.480656.10740.nullmailer () svn ! kde ! org
[Download RAW message or body]

SVN commit 1101899 by zander:

Updated the old rules to be more encompassing

 M  +78 -7     README  


--- trunk/koffice/libs/README #1101898:1101899
@@ -1,16 +1,61 @@
-KOffice libs uses so called CamelCase naming for all files in the libraries.
-Example:  KoParagDia.cpp
+KOffice libs is a collection of libraries for very different functionality
+with the common denominator that some KOffice applications depend on it.
+Each of the libraries have a Mainpage.dox file which is used for API docs
+and it should contain an overview of the library goal and scope. If you
+add a class you should likely read this before deciding where it goes.
+
+Various details can also be found here;
+  http://wiki.koffice.org/index.php?title=Libs
+
+
+At this point in time (early 2010) all of the libraries in here are not
+guarenteed to have binary or source compatibility between releases.
+However there is a strong push to make a subset of libraries become
+more used outside of KOffice and thus they need to be backwards compatible
+between releases. Which in effect means that we are working towards them
+becoming Binary and Source (and behavior) compatible between releases.
+
+
+General policies
+================
+
+All code in KOffice libs that will be released shall be licensed under the
+terms of the GNU Library General Public License as published by the Free
+Software Foundation; either version 2 of the License, or any later version.
+
+All libraries shall be able to compile as the first and/or only part of KOffice.
+Which effectively means anything in libs can not depend on another part of
+KOffice outside of the libs.
+
+
+Code submit policies
+====================
+
+For code and files in KOffice/libs we have some rules.
+As KOffice is part of KDE we follow the KDE policies;
+    http://techbase.kde.org/Policies
+more specifically, for all of the code under koffice/libs we follow the coding style
+  http://techbase.kde.org/Policies/Kdelibs_Coding_Style
+
+
+Naming
+======
+
+All of KOffice libs uses so called CamelCase naming for all files in the libraries.
+Example:  KoParagaphDialog.cpp
 File extensions are always .cpp and .h
 We prefer one class per file.  This is to make the filename match the class, which
 obviously does not work if there is more then one class in the file.
 When there is a private class that is not used outside the file it's ok to have it
 in the same file as another class.
-Private classes that should never be exported or used outside the library should be
-placed in a header file with the extention _p.h  (like KoRulerPrivate_p.h)
-This makes it very obvious this file is not part of the public API of koffice.
+Private classes that should never be exported or used outside the library and should be
+placed in a header file with the extention _p.h  (like KoRuler_p.h)
+This makes it very obvious this file is not part of the public API of KOffice.
 
-KOffice and Namespaces
-======================
+
+Namespaces and more naming
+==========================
+
 KOffice in general does not use namespaces, but uses a prefix for each class.
 Application maintainers may have a slightly different rule.
 
@@ -27,3 +72,29 @@
 Kis for Krita (from KImage-shop)
 
 
+Backwards compatibility for some libs
+=====================================
+
+For libraries that are going to have usage outside of KOffice they have some extra
+rules to make sure they are backwards compatible between releases.
+The list of libraries that this applies to is;
+ * koodf
+ * koplugin
+ * pigment
+ * flake
+ * kotext
+
+on top of the above list of guidelines there are some more for these that have
+to be taken into account when modifying them or adding new code.
+  http://techbase.kde.org/Policies/Library_Code_Policy
+  http://techbase.kde.org/Policies/Library_Documentation_Policy
+
+Not a rule, but often used in KOffice libs is the shared-d-pointer. As this
+is a trick that is a bit tricky lets use this place to point to an excellent
+example. Make sure to use when appropriate. (ask if in doubt)
+  http://techbase.kde.org/Policies/Library_Code_Policy/Shared_D-Pointer_Example
+
+
+Final rule, the common sense rule :)
+If in doubt about any code change, post a review request for your change!
+
[prev in list] [next in list] [prev in thread] [next in thread]