Added developer-abandoned KDE3 version of Digikam

git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/applications/digikam@1075997 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 287 insertions, 0 deletions

diff --git a/HACKING b/HACKING
new file mode 100644
index 0000000..cd6690f
--- /dev/null
+++ b/HACKING
@@ -0,0 +1,287 @@
+This file's purpose is to guide contributors and developers to help on the
+digiKam project.
+
+========================================================================
+10 golden rules for starting with open source
+========================================================================
+
+Before to contribute to digiKam project, please take a look to this link:
+
+http://schlitt.info/applications/blog/index.php?/archives/541-10-golden-rules-for-starting-with-open-source.html
+
+========================================================================
+Source code formatting:
+========================================================================
+
+Adhere to this style guide strictly while adding new code to digiKam or 
+working on existing code. 
+
+-------------------------------------------------------------------------
+* Indentation length
+-------------------------------------------------------------------------
+
+Indent with 4 spaces exactly.
+
+for eg:
+
+void function()
+{
+....int a;                    // 4 spaces from beginning
+....for (int i=0; i<10; i++)  // 4 spaces from beginning
+....{                         // 4 spaces from beginning
+........a = i;                // 4 spaces from previous indent block
+
+Emacs by default will indent to 4 spaces
+vim users add this to you .vimrc
+ set tabstop=4        
+
+-------------------------------------------------------------------------
+* Tabs vs Spaces
+-------------------------------------------------------------------------
+
+Absolutely no tabs. Use a sensible editor which will convert tabs to spaces. 
+This will reduce unnecessary changes in your cvs commits.
+
+Emacs by default will convert tab to spaces.
+For vim users, add this to your .vimrc
+  set expandtab
+
+-------------------------------------------------------------------------
+* Line length
+-------------------------------------------------------------------------
+
+Line length should never exceed 80 chars (unless really necessary - these 
+cases are rare). Having long lines greatly reduces readability of code
+
+-------------------------------------------------------------------------
+* Bracketing
+-------------------------------------------------------------------------
+
+In almost all cases, {} brackets should start on a newline and should be 
+aligned with previous line (follow the indentation spaces). for eg.
+
+class A 
+{ //new line
+...
+
+for (int i=0; i<10; i++)
+{ //new line
+
+if (a == foobar)
+{ //new line
+... 
+}
+else
+{ // new line
+..
+} 
+
+-------------------------------------------------------------------------
+* Positioning of Access modifiers
+-------------------------------------------------------------------------
+
+public, private, protected, public slots, ... should be aligned to the 
+beginning of the line with no margin
+
+class A
+{
+public: // aligned to left 
+...
+private slots: // aligned to left 
+
+
+Follow a consistent order in defining these attributes. The recommended
+order is public, protected (functions), private (functions), 
+signals, public slots, protected slots, private slots, private (variables)
+
+========================================================================
+Class, file and Variable names:
+========================================================================
+
+-------------------------------------------------------------------------
+* Class and filenames
+-------------------------------------------------------------------------
+
+- filenames should always be in lower-case 
+- class names should match the filenames. Capitalize the first letter and
+  other letters logically to improve readability
+
+-------------------------------------------------------------------------
+* Protected Member variables
+-------------------------------------------------------------------------
+
+- protected member variable names should always be of the form m_varName. 
+- Captilize logically so that it becomes easy to read it. Do not capitalize
+  the first letter after _ (Use m_varName not m_VarName)
+- variable names should be indicative of their functionality and also of 
+  the type they belong too if they are instances of qt widgets.
+  for eg, QCheckBox* m_autoRotateCheckBox;
+
+-------------------------------------------------------------------------
+* Non-Member variables
+-------------------------------------------------------------------------
+
+- non-member variables should follow the same naming convention as the member 
+  variables, except for the leading m_
+
+-------------------------------------------------------------------------
+* Private Member variables
+-------------------------------------------------------------------------
+
+- private member variables must be stored in a d private container to reduce
+  compilation time and improve binary compatibilty between digiKam components.
+  See more informations how to use a 'd' private class at this url: 
+
+  http://developer.kde.org/policies/librarypolicy.html
+
+========================================================================
+Comments and Whitespace
+========================================================================
+
+Use whitespaces liberally to improve readability. Add blank lines between logical
+sections of the code.
+
+Comment as much as possible. Position comments at the beginning of the
+section/line you want to comment, NEVER at the end of the line
+
+// put your comments here
+a = (b == foobar) ? 1 : -1; 
+
+a = (b == foobar) ? 1 : -1; // you are asking for trouble by putting comments here
+
+
+========================================================================
+Header files
+========================================================================
+
+- Add copyright to top of every file. Use the same header than others digiKam
+  source code.
+- Double inclusion protection defines are all upper case letters and are 
+  composed of the classname and a H suffix separated by underscore
+
+#ifndef ANOTHERNICECLASS_H
+#define ANOTHERNICECLASS_H
+
+class AnotherNiceClass
+{
+...
+}
+
+#endif
+
+- Use forward declarations as much as possible.
+
+class QFileInfo;
+
+class A
+{
+....QFileInfo* m_fileInfo;
+
+========================================================================
+General recommendations
+========================================================================
+
+Please take a look into KDE contrib page tips before to write code/patches for 
+digiKam project : http://techbase.kde.org/Contribute
+
+Use the same .cpp/.h header than the rest of digiKam project.
+
+Use a decent editor which does auto-indentation/syntax-highlighting for you. 
+I personally use Emacs (Renchi) or Kdevelop (Gilles).
+There are excellent initializer scripts in the kdesdk
+package for xemacs and vim which can substantially increase your productivity.
+
+Just to give a taste of what i can do with emacs (and kdesdk):
+
+* automatically insert copyright (and ifdefs) in new files.
+* insertion of class function definitions for declared class 
+  functions in header with one keystroke
+* switch between header and declaration files with one keystroke
+* go to corresponding definition/declaration with one keystroke
+* tab completion of variable/function names already declared.
+
+========================================================================
+GDB Backtrace 
+========================================================================
+
+If you found a context to crash digiKam, you can provide a backtrace using GDB debugger.
+digiKam need to be compiled with all debug info else the backtrace will not suitable.
+There is a configure option for that:
+
+# make -f Makefile.cvs
+# ./configure --enable-debug=full
+# make
+# su
+# make install.
+
+To make a backtrace with GDB use following command:
+
+# gdb digikam
+> run
+> ...
+> _crash here_
+> ...
+> bt
+> _the backtrace is here_
+> quit
+
+Post this backtrace at the right place (B.K.O or devel ML) for investigations by developers.
+
+========================================================================
+Memory leak 
+========================================================================
+
+To check any memory leak problem in digiKam, valgrind is your friend (http://valgrind.org)
+Try this command line to use with valgrind :
+
+valgrind --tool=memcheck --leak-check=full --error-limit=no digikam
+
+========================================================================
+Profiling with cachegrind
+========================================================================
+
+Valgrind also includes a tool to find out in which parts of your code time is spent.
+
+valgrind --tool=callgrind digikam
+
+Profiling can be disabled at startup to limit the output to the code you are interested in.
+Start with
+
+valgrind --tool=callgrind --instr-atstart=no digikam
+
+and prepare the situation you want to profile. Then, in another console, start profiling with
+"callgrind_control -i on" and, after the situation has passed, request a profile dump with
+"callgrind_control -d".
+The resulting callgrind.out files need to be viewed with the kcachegrind program, e.g.:
+
+kcachegrind callgrind.out.16693.1
+
+=================================================================================
+API Documentation Validation, User Documentation Validation, Source Code Checking
+=================================================================================
+
+The following site check on a dayly basis for the a.m. errors:
+www.englishbreakfastnetwork.org/krazy/
+
+It can be very useful, in particular before major releases.
+Don't trust it blindly! Sometimes they propose too advanced modifications that are no compatible with the prevailant include files.
+
+========================================================================
+Usability issues
+========================================================================
+
+OpenUsability project has define default menu structure and keyboard shortcuts:
+
+http://wiki.openusability.org/guidelines/index.php/Appendices:Keyboard_Shortcuts
+
+========================================================================
+Generate API documentation
+========================================================================
+
+To generate API documentation, you need to install:
+
+- Doxygen program (http://www.doxygen.org).
+- Dot program (http://www.graphviz.org)
+
+Go to 'project' sub-folder and just run doxygen binary program. A new subfolder 
+named 'api' will be create. Warning, this can take a while.